De phpDocs headers om je IDE te vertellen welke properties je Laravel modellen hebben is een onmisbare feature. Maar hoe zorg je er voor dat deze ook altijd toegevoegd worden tijdens development? Onze oplossing; een check aan je CI toevoegen zodat een build failed op het moment dat deze missen.

Laravel is een mooi en flexibel framework waar je krachtige applicaties in kunt bouwen. 
Maar omdat we in FLOW (https://flow.neos.io/) gewend waren dat je in je IDE eenvoudig door kunt klikken op model properties, was dit eerst wel even vreemd na de overstap naar Laravel. Laravel heeft veelal dynamische properties, met name in de model classes.

Gelukkig kun je je classes voorzien van extra commentaar in je doc blocks waardoor je IDE ook deze dynamisch properties herkend en je dus alle kracht van je IDE kunt benutten. Maar om dit allemaal zelf te schrijven is natuurlijk geen doen, Barry vd. Heuvel (https://github.com/barryvdh) heeft hier een aantal mooie helper tools (https://github.com/barryvdh/laravel-ide-helper) voor geschreven die je eenvoudig aan je project kunt toevoegen. 

Om de code aan je project toe te voegen en dan een regel in de `register()` functie van `app/Providers/AppServiceProvider.php` om de commandos registreren.

Na installatie heb je 3 extra artisan commando’s tot je beschikking.

• 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

Voor meer info over de specifieke opties zie de laracast video met uitleg https://laracasts.com/series/how-to-be-awesome-in-phpstorm/episodes/15

In ons team hebben we besloten voor de php artisan ide-helper:models optie te gaan. Wat inhoudt dat ieder model wordt voorzien van extra phpDocs zodat je IDE alle dynamische properties en relaties herkend.
Dit werkt allemaal super mits iedereen het commando ook runt na het toevoegen van nieuwe velden/relaties aan de database.  Helaas werd dit wel eens vergeten en ook bij de code reviews werd dit niet altijd gezien.

Tijd voor wat automatisering zodat we dit niet meer kunnen vergeten. De tests in de CI mogen gewoon niet groen worden totdat dit er in zit. Daarom hebben we dit toegevoegd aan de test die na ieder push naar onze git repos zodat er gecontroleerd wordt of de phpDocs wel compleet zijn.

Helaas kun je niet zoals php linting/php-cs-fixer het commando standalone draaien. Je zult een actieve database nodig hebben zodat het commando de databasevelden kan matchen met de aanwezige modellen. Wij hebben er voor gekozen om dit als laatste stap na de phpunit tests toe te voegen omdat we daar al een database beschikbaar hebben.

Hoe weet je nu of er een phpDoc regel mist, het php artisan ide-helper:models commando geeft geen `exit 1` als er iets mist  en heeft ook geen optie om dit te forceren. We hebben dit opgelost door de `git status` hiervoor te gebruiken.

1. eerst zorgen we dat de repo schoon is van wijzigingen `git reset`
2. dan runnen we het commando php artisan ide-helper:models
3. dan gebruiken we `git status --porcelain` om te checken of er wijzigingen zijn

Zijn er wijzigingen dan geven we een `exit 1` waardoor de test failed en de dev ziet dat er iets mist.

We merkte dat in sommige projecten waar we ook zelf commentaar aan de modellen hadden toegevoegd we “false negatives” kregen. De `git status` check gaf aan dat er wijzigingen waren, maar dit waren alleen wat extra spaties die er sowieso niet mochten staan.

Om hier omheen te werken voeren we nog een `vendor/bin/php-ci-fixer fix` uit om deze spaties weer te verwijderen. En hadden we geen problemen meer met foute resultaten.

De `git reset` bleek achteraf ook niet nodig te zijn na het toevoegen van `.composer` aan ons `.gitignore` bestand. We gebruiken GitLab voor het runnen van de CI taken en daar wordt in onze setup `.composer` gebruikt als cache folder voor Composer. Na het toevoegen van deze folder aan de `.gitignore` was de `git reset` niet meer nodig en ziet onze `gitlab-ci.yaml` er nu als volgt uit.