Laravel Model Doc Laravel Package

Product Decisions This Supports

• Developer-experience investment sizing. This package is a concrete, near-zero-cost lever for the "our models are undocumented and IDE autocomplete is useless" complaint. It lets you scope a DX initiative as a tooling rollout rather than an engineering project, and it gives you a measurable baseline (how many models lack @property blocks today).
• Build vs. buy for internal codegen. If anyone has proposed an internal script that reads the schema and writes PHPDoc onto Eloquent models, this is the buy-side option to evaluate first. The honest comparison is against a ~1-day internal spike, not against a vendor contract — which means the decision hinges on maintenance appetite and edge-case coverage, not price.
• Static-analysis roadmap. Raising PHPStan/Larastan levels on a Laravel codebase stalls on undeclared model properties. Generated @property blocks are the cheapest way to unblock a level bump, so this package can be the enabling dependency behind a "we go to level 6 next quarter" commitment.
• Onboarding and legacy-audit use cases. For inherited or acquired Laravel codebases, running the generator produces a readable schema-to-code map. That's useful for due diligence, handover docs, and estimating the cost of a refactor.
• Committed-vs-CI policy for generated artifacts. Adopting this forces a decision you'll need anyway: do generated docblocks live in VCS, or run in CI as a drift check (generate + git diff --exit-code)? That policy generalizes to every other codegen tool you add.
• Tooling consolidation. It overlaps materially with barryvdh/laravel-ide-helper. Any adoption decision here is really a "do we add a second doc generator, or extend the one we have?" decision.

When to Consider This Package

Adopt when:

• You have a meaningful model count (roughly 20+) with schemas that churn, so hand-maintained docblocks are guaranteed to rot.
• The team's typing convention is docblock-based (@property, @method) rather than PHP 8 attributes or fully typed DTOs.
• You already run or plan to run Larastan/PHPStan and want a mechanical fix for the "undefined property" class of errors.
• You're comfortable pinning a version and, if necessary, forking — the project is MIT, single-maintainer, 32 stars, zero dependents.
• The models are conventionally structured (standard columns, standard relationship methods). Generated output is only as good as the generator's inference.

Look elsewhere when:

• larryvdh/laravel-ide-helper (or an equivalent) is already in the stack. Adding a second generator buys you overlap, not capability, and splits the "which tool owns docblocks" question.
• Your model count is small enough that a lint rule plus code review is cheaper than a new dependency.
• You're migrating to PHP 8 attributes, native typed properties, or generated DTOs — docblock generation is investing in the pattern you're leaving.
• Models rely heavily on custom casts, accessors/mutators, JSON columns, or non-standard schema drivers where inference is likely to be incomplete or wrong. Wrong docblocks are worse than none: they silence static analysis on real bugs.
• You need runtime guarantees. This is a static hint generator, not validation.
• Your dependency policy excludes low-adoption packages. Zero dependents and a low opportunity score mean you should assume you are the maintainer of last resort.

How to Pitch It (Stakeholders)

To executives: This is a dev-only, MIT-licensed utility with no runtime footprint and no production risk. It automates a chore — keeping model documentation in sync with the database — that engineers currently do by hand or skip. The upside is faster onboarding, fewer trivial static-analysis failures, and better IDE autocomplete; the cost is an afternoon of evaluation. Because adoption is small (32 stars, no dependents, single maintainer), frame it as an internal convenience tool, not a strategic dependency: pilot it on one service, and budget for the possibility that we pin or fork it.

To engineering: The tool reads your schema and writes @property/@method blocks onto Eloquent models. The realistic value is unblocking a Larastan level increase and killing the "what columns does this model have?" question in review. Two caveats to agree on up front: (1) decide whether generated blocks are committed or enforced in CI as a drift check, and (2) audit output on models with custom casts, accessors, and JSON columns before trusting it — bad docblocks suppress real errors. Recommend a one-sprint trial on a bounded service, comparing against laravel-ide-helper if it's already present, with a go/no-go based on measured time saved and how much manual correction the generated output needs.