https://github.com/saproto/saproto
This repository holds the ICT environment for Study Association Proto, the study association for Creative Technology and Interaction Technology at the University of Twente.
https://github.com/saproto/saproto
hacktoberfest laravel php
Last synced: 5 months ago
JSON representation
This repository holds the ICT environment for Study Association Proto, the study association for Creative Technology and Interaction Technology at the University of Twente.
- Host: GitHub
- URL: https://github.com/saproto/saproto
- Owner: saproto
- License: gpl-3.0
- Created: 2015-11-24T19:16:58.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2026-02-01T22:34:58.000Z (5 months ago)
- Last Synced: 2026-02-01T23:23:51.752Z (5 months ago)
- Topics: hacktoberfest, laravel, php
- Language: PHP
- Homepage: https://www.proto.utwente.nl/
- Size: 118 MB
- Stars: 18
- Watchers: 8
- Forks: 11
- Open Issues: 98
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
S.A. Proto
The website of S.A. Proto.
The study association of BSc. Creative Technology and MSc. Interaction Technology.
## Contributors
[Here](https://github.com/saproto/saproto/graphs/contributors) you can find the people that have contributed to the code
to this project. But, let's not forget the other members of
the [HYTTIOAOAc](https://www.proto.utwente.nl/committee/haveyoutriedturningitoffandonagain)!
## Prerequisites
This README is tailored to using Docker in WSL2 (Ubuntu) on Windows using Laravel Sail. Laravel Sail also supports MacOS
and Linux, however you may encounter issues with the installation instruction below when using a different operating
system.
Before following the installation instructions, you need to have a working installation of WSL2, Docker and Git. You can
install docker using the official instructions at [docs.docker.com](https://docs.docker.com/get-docker).
JetBrains [PhpStorm IDE](https://www.jetbrains.com/help/phpstorm/installation-guide.html) is strongly recommended for
development on this project, especially with the laravel plugin for proper code completion and reverences.
## Setup
This website can be run locally through Docker by using Laravel Sail. For more information on using Laravel Sail check
out their [documentation](https://laravel.com/docs/sail).
### Download
First you need to clone the repository into a folder in WSL2.
#### If you set an SSH key:
```
git clone git@github.com:saproto/saproto.git
```
#### Otherwise, use HTTPS:
```
git clone https://github.com/saproto/saproto.git
```
### Installation
After installing Docker and cloning the repository the following instructions can be run in the terminal in the source
folder of the project.
#### Configuration
Copy and rename `.env.dev` to `.env`.
```
cp .env.dev .env
```
After that, open the new `.env` file and set the `PERSONAL_PROTO_KEY` to your personal Proto key, which can be
found/generated on the bottom of [your dashboard](https://www.proto.utwente.nl/user/dashboard) on the ***live*** Proto
website.
#### Server-side dependencies
When first cloning the project you may not have a functional installation of the correct version of PHP or Composer. To
install Laravel sail and its dependencies it is therefore necessary to spin up a temporary container.
```shell
docker run --rm \
-u "$(id -u):$(id -g)" \
-v $(pwd):/var/www/html \
-w /var/www/html \
laravelsail/php82-composer:latest \
composer install --ignore-platform-reqs --no-scripts
```
#### Laravel Sail alias
By default, Laravel Sail commands are invoked using the `vendor/bin/sail` script. That is a lot of characters to type
every time you want to execute a command. So, instead you can create an alias. By adding the alias definition
to `~/.bash_aliases` (WSL2/Linux) or `~/.zshenv` (macOS) the alias will persist between terminal restarts.
*The rest of these instruction will assume that you successfully added the `sail` alias.*
WSL2/Linux/macOS High Sierra or earlier:
```shell
echo "alias sail='[ -f sail ] && bash sail || bash vendor/bin/sail'" > ~/.bash_aliases
```
macOS Catalina or newer:
```shell
echo "alias sail='[ -f sail ] && bash sail || bash vendor/bin/sail'" > ~/.zshenv
```
#### Initial application setup
```
sail up -d
sail composer install
sail artisan key:generate
sail artisan webpush:vapid
sail artisan migrate --seed
```
#### Client-side dependencies
To install the client-side dependencies you'll need to run `sail npm install` to install all client-side dependencies.
To compile the project assets (JS/CSS) run `sail npm run build` to compile once or `sail npm run dev` to keep checking
for changes to scripts or stylesheets.
When adding a new library or client-side dependency through npm don't forget to require the scripts in `application.js`
and the stylesheet in `vendor.scss`.
#### WebPush notifications
For WebPush notifications we use the [webpush](https://github.com/laravel-notification-channels/webpush) notification channels.
To set it up you need to generate the vapid keys once by running:
`sail artisan webpush:vapid`
#### Websockets
In some parts of the website we use websockets to update the page in real-time.
For this we use a soketi server. This runs in a docker container in your sail setup.
For the frontend we use the [Laravel Echo](https://laravel.com/docs/broadcasting) library to connect to the
websocket server.
#### Localhost
When you have finished the above setup the following port will be exposed on localhost.
- `8080` = Website
- `8081` = PhpMyAdmin
- `8082` = [Mailpit](https://github.com/axllent/mailpit)
You can sign in with the same Proto username you use on the ***live*** website and the password given to you during the
database seeding. This user will have full admin rights on the ***local*** website.
#### Known WSL2 + Git issue
Due to the permission changes, Git might detect that all files have been changed. If this is the case,
run `git config core.filemode false` to make git ignore the permission changes.
### Useful commands
#### Start server
```
sail up -d
```
#### Stop server
```
sail stop
```
#### Access to app container
```
sail shell
```
#### Nuke your database *(run in container)*
```
sail artisan migrate:fresh --seed
```
### Code completion, style and static analysis
##### IDE-helper
When writing code it is useful to have tools such as code completion and linting in an integrated development
environment (IDE). As mentioned before [PHPStorm](https://www.jetbrains.com/phpstorm/) is the recommended IDE for this
project. To add additional code completion for Laravel you can run `sail composer ide-helper` in the docker container to
let [Laravel-IDE-Helper](https://github.com/barryvdh/laravel-ide-helper) generate an `_ide_helper.php` file which tells
PHPStorm what certain classes and function are, so it can perform proper code completion and show documentation.
##### PHP-CS-Fixer
Run `sail composer fix` in the docker container to fix stylistic errors in your code
using [PHP-CS-Fixer](https://github.com/FriendsOfPHP/PHP-CS-Fixer). This will also be done automatically when creating a
pull-request or pushing to a branch with an open pull-request.
##### Laravel Rector
Run `sail composer rector` in the docker container to automatically upgrade your code
using [Laravel-Rector](https://getrector.com/documentation) to meet the rules set in rector.php.
This will also be done automatically when creating a
pull-request or pushing to a branch with an open pull-request.
##### Larastan
There is also the option for static analysis of your code. Run `sail composer analyse` in the docker container to
let [Larastan](https://github.com/nunomaduro/larastan) find any potential bugs in your code.
## Debugging
### Xdebug
Xdebug is activated in Laravel Sail to aid you while debugging the website. Xdebug enables breakpoints and step
debugging which can easily be controlled from your IDE. For this to work, you will have to set up your IDE correctly.
#### Xdebug in PhpStorm
PhpStorm for zero-configuration debugging. In case of zero-configuration debugging, you do not need to create any debug
configuration. Instead, you open the starting page of your PHP application in the browser manually, and then activate
the debugging engine from the browser, while PhpStorm listens to incoming debugger connections. For full instructions on
how to use zero-configuration debugging, check out
the [PhpStorm documentation](https://www.jetbrains.com/help/phpstorm/zero-configuration-debugging.html)
### Clockwork
[Clockwork](https://underground.works/clockwork) is a php dev tool in your browser. When running the website in debug
mode you can access the clockwork debug page at . The application has various debugging
features such as timelines of runtime requests, database queries and client-metrics.
### Testing
For testing we use Pest for testing.
These tests should be run locally, but are also run on every PR in GitHub Actions.
If tests are failing, and it shows that all the tests using a database fail, you should run
```sail artisan optimize:clear``` first.
#### Pest
The Pest tests can be run with the following command:
```sail test```.
If you do not need the output and want it to go faster you can use the ```--parallel``` flag.
To make a new test you can use the following command:
```sail artisan make:test {{TestName}}```.
To make a unit test you can use the following command:
```sail artisan make:test {{TestName}} --unit```.