Test for missing IDE-helper PHPDoc blocks
The phpDocs headers to tell your IDE which properties your Laravel models have, are an indispensable feature. But how do you make sure they are always added during development? Our solution; adding a check to your CI so a build fails the moment they are missing.
Laravel is a beautiful and flexible framework where you can build powerful applications.
But because we were accustomed to FLOW (https://flow.neos.io/) that you can simply click on model properties in your IDE, this was a bit strange after the switch to Laravel. Laravel often has dynamic properties, especially in the model classes.
Fortunately, you can provide your classes with extra comments in your doc blocks so your IDE recognizes these dynamic properties and you can use all the power of your IDE. But to write all this yourself is of course not to do, Barry vd. Heuvel (https://github.com/barryvdh) has written a number of beautiful helper tools (https://github.com/barryvdh/laravel-ide-helper) that you can easily add to your project.
Installation is simple
To add the code to your project and then a line in the `register ()` function of `app / Providers / AppServiceProvider.php` to register the commands.
After installation you have 3 additional artisan commands at your disposal.
- php artisan ide-helper:generate - phpDoc generation for Laravel Facades
- php artisan ide-helper:models - phpDocs for models
- php artisan ide-helper:meta - PhpStorm Meta file
For more info about the specific options see the laracast video with explanation https://laracasts.com/series/how-to-be-awesome-in-phpstorm/episodes/15
In our team we decided to go for the php artisan ide-helper:models option. This means that each model is provided with extra phpDocs so that your IDE recognizes all dynamic properties and relationships.
This all works great as long as everyone runs the command after adding new fields / relations to the database. Unfortunately this was sometimes forgotten and was not always seen with the code reviews.
Time for some automation so that we can not forget this. The tests in the CI may simply not turn green until it is in it. That is why we added this to the test that after each push to our git repos so that it is checked whether the phpDocs are complete.
Unfortunately, you can not run the command standalone like php linting / php-cs fixer. You will need an active database so that the command can match the database fields with the existing models. We have chosen to add this as the last step after the phpunit tests because we already have a database available there.
Check your PhpDoc rule
How do you know if there is a phpDoc rule? The php artisan ide-helper:models command does not give 'exit 1' if something is missing and also has no option to force it. We solved this by using the `git status` for this.
- first we ensure that the repo is clean of changes `git reset`
- then we run the command php artisan ide-helper: models
- then we use `git status - porcelain` to check if there are any changes
- if there are any changes then we give an 'exit 1' which makes the test failed and the dev sees something missing.
We noticed that in some projects where we also added comments to the models, we received "false negatives". The `git status` check indicated that there were changes, but these were only extra spaces that were not allowed anyway.
To work around this, we run a `vendor / bin / php-ci-fixer fix` to remove these spaces again. And we no longer had problems with wrong results.
The `git reset` also turned out not to be necessary after adding` .composer` to our `.gitignore` file. We use GitLab to run the CI tasks and in our setup `.composer` is used as cache folder for Composer. After adding this folder to the `.gitignore` the` git reset` was no longer needed and our `gitlab-ci.yaml` now looks like this.
Run PHP tests: stage: test services: - mysql:5.7 script: - echo "Build laravel" - composer install --no-ansi --no-interaction --no-progress --classmap-authoritative 2>&1 # Testing with sql-lite - cp .env.testing-sqllite .env - touch test.db - php artisan key:generate - php artisan migrate - echo "Run php tests" - ./vendor/bin/phpunit --colors # Run ide-helper command - php artisan ide-helper:models -W # Run fixer to remove left over spaces created by the ide-helper command - vendor/bin/php-cs-fixer fix - git status - if [[ `git status --porcelain` ]]; then echo "Missing some ide-helper PHPDocs run \`php artisan ide-helper:models -W\`"; exit 1; else echo "ide-helper PHPDocs OK"; fi