Laravel Model Annotator Laravel Package

Product Decisions This Supports

• Build vs. buy for internal DX tooling. If your team has ever hand-written or scripted @property / @method docblocks on Eloquent models, this is a candidate replacement for that homegrown script. The decision is small in scope but real: adopt a dependency vs. maintain ~50 lines of internal tooling.
• Whether to invest in static analysis as a CI gate. Model annotations are a prerequisite for PHPStan/Larastan or Psalm to give you meaningful type coverage on Eloquent models. If you're deciding whether to raise the static-analysis level in CI, a generator like this moves the starting line from "models are untyped mixed" to "models have property and relation types."
• IDE/autocomplete parity for domain models. A concrete, measurable DX outcome: $order->customer-> autocompletes instead of requiring a trip to the schema or the migration files. This feeds onboarding-time and "time to first PR" metrics more than it feeds roadmap.
• Legacy codebase audit before a refactor. Because the command reads schema, relationships, and casts and emits them, running it over an inherited or under-documented codebase is a cheap way to surface the domain model — what's related to what, which casts exist, where schema and code have drifted. That's useful input to scoping a refactor or a data migration.
• Refactor scope signals. Annotating relationships tends to expose missing inverse relations, casts defined on the model that no longer match the column type, and accessors that shadow real attributes. Useful for prioritising cleanup work, not for customer-facing roadmap.
• Honest framing for the roadmap: this is developer-productivity tooling. It does not affect runtime behaviour, customer experience, or performance. Treat it as a line item in a DX/onboarding initiative, not a product bet.

When to Consider This Package

Consider it when:

• Your models lack docblocks and your team uses PHPStorm, PHPStan/Larastan, or Psalm — the annotations are immediately useful.
• You specifically want annotations written into the model files themselves rather than into a separate generated helper file (this is the main functional difference from the dominant alternative).
• You're running a narrow evaluation spike and are comfortable pinning a version, reading the source, and forking if needed.
• The app's models are reasonably conventional — standard columns, standard relations, standard casts.

Look elsewhere when:

• You haven't evaluated barryvdh/laravel-ide-helper yet. It is the mature, widely-adopted incumbent and its ide-helper:models command covers the same ground, including writing into model files. With 0 stars, 0 dependents, and a score of 0, this package has essentially no production evidence behind it. Default to the incumbent; adopt this only if a spike shows a clear, specific advantage.
• Your models are heavily customised. Generators routinely get confused by custom cast classes, dynamic/computed attributes, polymorphic or through-relations, and multi-connection setups. Verify output correctness on your three ugliest models before trusting it repo-wide.
• You need support, an SLA, or community answers. Zero dependents means zero battle-testing and near-zero chance of a Stack Overflow answer when it emits wrong annotations.
• You expected runtime benefit. This is a dev-only tool with no runtime footprint — a feature, not a limitation, but worth stating plainly so nobody expects it to fix N+1s.
• Abandonment risk is unacceptable. Mitigation is cheap here: it's MIT, dev-dependency only, and removable in an hour. If that mitigation isn't acceptable, don't adopt.

Practical adoption guardrails: install as require-dev, pin the version, run it via CI diff-check (fail the build if regenerated annotations drift), and keep a one-line fallback plan: switch to laravel-ide-helper or vendor the command.

How to Pitch It (Stakeholders)

To executives: A small, free, MIT-licensed developer tool that auto-documents our database models so our IDEs and code-quality checks understand them. It's a dev-only dependency with no runtime footprint and no customer impact, and it can be removed in about an hour if we don't like it. The upside is faster onboarding and fewer "what columns does this table have" interruptions; the cost is one dependency and a short evaluation spike. Low cost, low risk, modest and honest upside — not a platform decision.

To engineering: One Artisan command that reads each Eloquent model's table schema, relations, and casts and writes them back as docblocks. Wins: IDE autocomplete on model properties and relations, and a real foundation for Larastan/PHPStan coverage at higher levels. Caveats we should be upfront about: the package has no adoption yet (0 stars, 0 dependents), so we treat it as unproven — spike it against laravel-ide-helper on our three messiest models first, pin the version, and wire it into CI as a diff check so annotations can't silently rot. If the spike isn't a clear win, we use the incumbent and lose nothing.