- What does romanzipp/laravel-model-doc do?
- It is a development-time PHPDoc generator for Laravel Eloquent models. It scans your models, introspects the database schema and relationship definitions, and writes @property and @method annotations into the model source files. That keeps IDE autocompletion and static analysis tools like Larastan/PHPStan and Psalm accurate without hand-maintaining docblocks.
- How do I install laravel-model-doc in a Laravel project?
- Install it as a dev dependency with composer require --dev romanzipp/laravel-model-doc, publish the config file if the defaults do not match your conventions, and then run the package's artisan command against your models. Because it is a dev-only utility it never needs to ship to production. Run it on a clean git branch first so you can review the generated diff before committing anything.
- Which Laravel and PHP versions does laravel-model-doc support?
- Check the package composer.json constraints before adopting it, since a small single-maintainer package can lag behind new Laravel majors. Verify the supported range covers both the oldest and newest PHP versions in your matrix. If your stack runs a recent Laravel release that is not yet covered, treat that as a blocker until you confirm support or patch it yourself.
- Does laravel-model-doc require a live database connection?
- In practice yes, because the generator needs to introspect your schema, so a reachable database is typically required at generation time. That means CI jobs must either provision a database service container for your driver or you commit pre-generated docblocks. Local development is simple since your normal .env database is already available.
- Will laravel-model-doc overwrite my hand-written PHPDoc and custom tags?
- The tool writes generated blocks into your model source files, so anything inside the block it manages can be rewritten. Custom tags, descriptions, and manual annotations should be tested on a representative model before you commit a full run. Generate on a branch and inspect the diff; if important documentation is clobbered, revert and consider excluding those models or isolating generated annotations.
- Can I use laravel-model-doc in CI to prevent documentation drift?
- Yes; the usual pattern is a job that regenerates the docblocks on a clean checkout and runs git diff --exit-code so any uncommitted change fails the build. That keeps generated annotations in sync as migrations evolve. The job needs a database service to introspect the schema, and you should confirm the available flags for limiting scope or dry-run output before wiring it up.
- How does laravel-model-doc handle casts, accessors, relationships, and custom table names?
- It derives annotations from the schema and from the relationship methods defined on your models, so standard belongsTo, hasMany, and morph relations are typically reflected. Custom casts, accessors, and non-standard table or column naming are the areas most likely to produce false positives or missing types. Test against a model that uses your most unusual conventions before rolling out broadly.
- Does laravel-model-doc affect production runtime or performance?
- No. It is a development-time code generation utility that sits entirely outside the request lifecycle and adds no deployed service-provider surface or runtime coupling. Installed with --dev it is not part of your production dependency footprint. The real cost is the source-file churn it introduces into your repository.
- Is laravel-model-doc actively maintained, and what are the alternatives?
- It has a modest community footprint, roughly 32 GitHub stars, few dependents, and a single maintainer, so abandonment risk is credible and Laravel major version lag is the most likely future blocker. The most common alternative is barryvdh/laravel-ide-helper, which also generates model PHPDoc but takes a different approach and has a much larger user base. Pinning the version and keeping a fork option open is a reasonable mitigation.
- How should I roll out laravel-model-doc across a large Laravel codebase?
- Start with a spike on one model in a single bounded context, on a clean branch, and review the diff quality and false positives. If it looks acceptable, roll out per domain or per team rather than repo-wide, because a first run over every model produces an unreviewable diff. Document a regeneration runbook and a conflict policy for parallel branches that touch the same model files.