Model properties come from the database and the analyser cannot see the schema, so a generated docblock is the bridge and it drifts on the next migration.
- run: php artisan ide-helper:models --nowrite --write-mixin
- run: |
if ! git diff --quiet; then
echo 'model docblocks are stale; run ide-helper:models' >&2
git diff --stat
exit 1
fi
Generating in CI and failing on a diff is what keeps them true, and it is the same pattern as any other generated artefact under version control. The alternative — trusting people to regenerate — produces docblocks that describe last quarter’s schema, which is worse than none because the analyser believes them.