Laravel Model Documenter Laravel Package

Getting Started

• Install with composer require patressz/laravel-model-documenter --dev (it's a dev tool that generates docblocks).
• Run php artisan model:document (or the equivalent command published by the package) to generate @property and @method docblocks on your Eloquent models.
• First use case: pick a single model with relationships and casts, run the command, and inspect the generated docblock. Iterate on config (paths, excluded models, docblock style) before running across the whole app/Models directory.
• Put the command in CI early: run it with --test to fail builds when docblocks drift, or --ci to regenerate and diff.

Implementation Patterns

• Local authoring loop: run the generator after adding relationships, casts, or accessors. Commit the docblock changes alongside the model change so IDE/static-analysis gains stay in sync.
• CI drift check: add a --test step to your pipeline after composer install and Pint. This catches models where the generated docblock no longer matches reality, without mutating files.
• Regenerate + commit in CI (--ci): for repos that prefer the bot to keep docs fresh, run with --ci, then git diff --exit-code to assert nothing changed—same effect as --test but with an actionable diff.
• Formatting integration: run Pint/php-cs-fixer before the drift check so import/fully-qualified-name normalisation has already happened. As of v1.1.2, imported class names are expanded to their fully-qualified form before comparison, so Pint's rewriting of @property/@method types no longer produces false "outdated" failures.
• Per-package config: if you have multiple models namespaces (e.g. modular app, package models), scope the generator paths in config rather than relying on scanning all of app/.
• Documentation as source of truth for statics: pair with PHPStan/Larastan—generated @property/@method docblocks let static analysis resolve magic attributes and relationship return types without per-model @phpstan- annotations.

Gotchas and Tips

• --ci / --test false positives (fixed in v1.1.2): prior versions compared raw class strings, so any model processed by Pint (which imports FQCNs in docblocks) was flagged as outdated on every run. Upgrade to ≥ v1.1.2 before wiring the drift check into CI.
• Ordering matters: run the linter before the drift check. If Pint runs after the --test step it will rewrite docblocks and your next run will still flag them—now not because of the bug, but because the generator ran against un-normalised input.
• Docblock churn in PRs: regenerating produces noisy diffs (ordering of @property/@method, blank lines). Configure stable ordering if the package exposes it, and commit generated docblocks in a dedicated commit to keep review diffs sane.
• Missing relationships: relationship @method entries are derived from the model's relationship methods—if a method's return type isn't an Eloquent relation or isn't typed, it won't be picked up. Add return types to relation methods.
• Casts and $appends: @property types follow casts and accessors; a custom accessor without a return type may generate a mixed/untyped property. Type your accessors.
• Excluding models: legacy or generated models (e.g. from a CRM SDK) can be excluded via config to avoid churn; otherwise every run touches files you don't own.
• Debugging "outdated" reports: when --test fails, run the generator without the flag and git diff the model—the diff shows exactly which property/method the tool thinks is stale, which is faster than reading the command's output.
• Extension point: the docblock writer/parser is typically swappable via config or container binding if you need a custom docblock header, custom tags, or to strip the tool's marker comments. Check config/model-documenter.php for the formatter binding before forking.