diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index a02b5421..6acbaa72 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -8,35 +8,16 @@ Please also read the [CONTRIBUTING.md](CONTRIBUTING.md). * Yarn (Development/Building only) * PHP Composer (Development/Building only) -## Local build -The following instructions explain how to get, build and run the latest Engelsystem version directly from the git main branch (may be unstable!). - -* Clone the main branch: `git clone https://github.com/engelsystem/engelsystem.git` -* Install [Composer](https://getcomposer.org/download/) and [Yarn](https://yarnpkg.com/en/docs/install) (which requires [Node.js](https://nodejs.org/en/download/package-manager/)) -* Install project dependencies: - ```bash - composer install - yarn - ``` - On production systems it is recommended to use - ```bash - composer install --no-dev - composer dump-autoload --optimize - ``` - to install the Engelsystem -* Build the frontend assets - * All - ```bash - yarn build - ``` - * Specific themes only by providing the `THEMES` environment variable, e.g. - ```bash - THEMES=0,1 yarn build - ``` -* Generate translation files - ```bash - find resources/lang/ -type f -name '*.po' -exec sh -c 'file="{}"; msgfmt "${file%.*}.po" -o "${file%.*}.mo"' \; - ``` +## Code style +Please ensure that your pull requests follow the [PSR-12](https://www.php-fig.org/psr/psr-12/) coding style guide. +You can check that by running +```bash +composer run phpcs +``` +You may auto fix reported issues by running +```bash +composer run phpcbf +``` ## Pre-commit hooks You should set up the pre-commit hook to check the code style and run tests on commit: @@ -54,87 +35,10 @@ Host machine: ln -s ../../bin/pre-commit .git/hooks/pre-commit ``` - -## Testing -To run the unit tests use -```bash -vendor/bin/phpunit --testsuite Unit -``` - -If a database is configured and the Engelsystem is allowed to mess around with some files, you can run feature tests. -The tests can potentially delete some database entries, so they should never be run on a production system! -```bash -vendor/bin/phpunit --testsuite Feature -# or for unit- and feature tests: -vendor/bin/phpunit -``` - -To run code coverage reports its highly recommended to use [`pcov`](https://github.com/krakjoe/pcov) or -at least `phpdbg -qrr`(which has problems with switch case statements) as using Xdebug slows down execution. -```bash -php -d pcov.enabled=1 -d pcov.directory=. vendor/bin/phpunit --testsuite Unit --coverage-text -``` - -### Var Dump server -Symfony Var Dump server is configured to allow for easier debugging. It is not meant as a replacement for xdebug but can actually be used together with xdebug. -This Var Dump Server is especially useful for when you want to debug a request without messing up the output e.g API calls ot HTML layout. - -To use simply call the method `dump` and pass the arguments in exactly the same way you would when using `var_dump`. - -This will send the output to the Var Dump server which can be viewed in the terminal. -This does however require that you start the var-dump-server otherwise the output will be printed in your browser - -You can also `dump` and `die` if you wish to not let your code continue any further by calling the `dd` method - -To view the output of `dump` call the following commands: - -```bash -vendor/bin/var-dump-server -# or for running in docker -docker-compose exec es_server vendor/bin/var-dump-server -``` - -For more information check out the Var Dump Server documentation: [Symfony VarDumper](https://symfony.com/components/VarDumper) - -## Translation -We use gettext. You may use POEdit to extract new texts from the sourcecode. -Please config POEdit to extract also the twig template files using the following settings: https://gist.github.com/jlambe/a868d9b63d70902a12254ce47069d0e6 - -## Code style -Please ensure that your pull requests follow the [PSR-12](https://www.php-fig.org/psr/psr-12/) coding style guide. -You can check that by running -```bash -composer run phpcs -``` -You may auto fix reported issues by running -```bash -composer run phpcbf -``` - -## CI & Build Pipeline - -The Engelsystem can be tested and automatically deployed to a testing/staging/production environment. -This functionality requires a [GitLab](https://about.gitlab.com/) server with a working docker runner. - -To use the deployment features the following secret variables need to be defined (if undefined the step will be skipped): -```bash -SSH_PRIVATE_KEY # The ssh private key -STAGING_REMOTE # The staging server, e.g. user@remote.host -STAGING_REMOTE_PATH # The path on the remote server, e.g. /var/www/engelsystem -PRODUCTION_REMOTE # Same as STAGING_REMOTE but for the production environment -PRODUCTION_REMOTE_PATH # Same as STAGING_REMOTE_PATH but for the production environment -``` - -## Static code analysis - -You can run a static code analysis with this command: - -```bash -composer phpstan -``` - ## Docker +We suggest using Docker for the Development local build. + If unspecific issues appear try using Docker version >= 20.10.14. This repo [ships a docker setup](docker/dev) for a quick development start. @@ -180,6 +84,107 @@ docker-compose exec es_workspace yarn build:watch docker-compose exec -e THEMES=0,1 es_workspace yarn build:watch ``` +## Localhost +You can find yout local Engelsystem on [http://localhost:5080](http://localhost:5080). + +## Local build without Docker +The following instructions explain how to get, build and run the latest Engelsystem version directly from the git main branch (may be unstable!). + +* Clone the main branch: `git clone https://github.com/engelsystem/engelsystem.git` +* Install [Composer](https://getcomposer.org/download/) and [Yarn](https://yarnpkg.com/en/docs/install) (which requires [Node.js](https://nodejs.org/en/download/package-manager/)) +* Install project dependencies: + ```bash + composer install + yarn + ``` + On production systems it is recommended to use + ```bash + composer install --no-dev + composer dump-autoload --optimize + ``` + to install the Engelsystem +* Build the frontend assets + * All + ```bash + yarn build + ``` + * Specific themes only by providing the `THEMES` environment variable, e.g. + ```bash + THEMES=0,1 yarn build + ``` +* Generate translation files + ```bash + find resources/lang/ -type f -name '*.po' -exec sh -c 'file="{}"; msgfmt "${file%.*}.po" -o "${file%.*}.mo"' \; + ``` + +## Testing +To run the unit tests use +```bash +vendor/bin/phpunit --testsuite Unit +``` + +If a database is configured and the Engelsystem is allowed to mess around with some files, you can run feature tests. +The tests can potentially delete some database entries, so they should never be run on a production system! +```bash +vendor/bin/phpunit --testsuite Feature +# or for unit- and feature tests: +vendor/bin/phpunit +``` + +To run code coverage reports its highly recommended to use [`pcov`](https://github.com/krakjoe/pcov) or +at least `phpdbg -qrr`(which has problems with switch case statements) as using Xdebug slows down execution. +```bash +php -d pcov.enabled=1 -d pcov.directory=. vendor/bin/phpunit --testsuite Unit --coverage-text +``` + +### Var Dump server +Symfony Var Dump server is configured to allow for easier debugging. It is not meant as a replacement for xdebug but can actually be used together with xdebug. +This Var Dump Server is especially useful for when you want to debug a request without messing up the output e.g API calls ot HTML layout. + +To use simply call the method `dump` and pass the arguments in exactly the same way you would when using `var_dump`. + +This will send the output to the Var Dump server which can be viewed in the terminal. +This does however require that you start the var-dump-server otherwise the output will be printed in your browser + +You can also `dump` and `die` if you wish to not let your code continue any further by calling the `dd` method + +To view the output of `dump` call the following commands: + +```bash +vendor/bin/var-dump-server +# or for running in docker +docker-compose exec es_server vendor/bin/var-dump-server +``` + +For more information check out the Var Dump Server documentation: [Symfony VarDumper](https://symfony.com/components/VarDumper) + +## Translation +We use gettext. You may use POEdit to extract new texts from the sourcecode. +Please config POEdit to extract also the twig template files using the following settings: https://gist.github.com/jlambe/a868d9b63d70902a12254ce47069d0e6 + + +## CI & Build Pipeline + +The Engelsystem can be tested and automatically deployed to a testing/staging/production environment. +This functionality requires a [GitLab](https://about.gitlab.com/) server with a working docker runner. + +To use the deployment features the following secret variables need to be defined (if undefined the step will be skipped): +```bash +SSH_PRIVATE_KEY # The ssh private key +STAGING_REMOTE # The staging server, e.g. user@remote.host +STAGING_REMOTE_PATH # The path on the remote server, e.g. /var/www/engelsystem +PRODUCTION_REMOTE # Same as STAGING_REMOTE but for the production environment +PRODUCTION_REMOTE_PATH # Same as STAGING_REMOTE_PATH but for the production environment +``` + +## Static code analysis + +You can run a static code analysis with this command: + +```bash +composer phpstan +``` + **Hint for using Xdebug with *PhpStorm*** For some reason *PhpStorm* is unable to detect the server name. diff --git a/docker/dev/docker-compose.yml b/docker/dev/docker-compose.yml index 6e7e6163..359e3f69 100644 --- a/docker/dev/docker-compose.yml +++ b/docker/dev/docker-compose.yml @@ -20,7 +20,7 @@ services: APP_NAME: Engelsystem DEV env_file: deployment.env ports: - - "5000:80" + - "5080:80" networks: - database - internet diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml index 59e3374e..239f04c3 100644 --- a/docker/docker-compose.yml +++ b/docker/docker-compose.yml @@ -12,7 +12,7 @@ services: MYSQL_PASSWORD: engelsystem MYSQL_DATABASE: engelsystem ports: - - "5000:80" + - "5080:80" env_file: deployment.env networks: - database