Laravel Model Documenter Laravel Package

Product Decisions This Supports

• Adopt automated model documentation as a standard practice. The package generates PHPDoc @property and @method annotations for Eloquent models, sourced from migrations/schema and model definitions. This removes a recurring manual chore and is the core build-vs-buy lever: buy (free, MIT-style OSS) versus building an internal generator.
• Enforce documentation freshness in CI. The --ci / --test modes turn "are the model docs still accurate?" into a pass/fail gate. This is the highest-leverage feature for a PM: it converts a documentation standard from a polite request into an automated check, which is the only kind of documentation standard that survives a busy sprint.
• Improve static analysis signal quality. Accurate @property and @method types let Larastan/PHPStan, Psalm, and IDE intelligence resolve model attributes, relationships, scopes, and accessors. This supports roadmap decisions around raising static-analysis levels without a multi-quarter typing initiative.
• Reduce onboarding and ramp-up cost. Models are where new engineers spend their first weeks in a Laravel codebase. Accurate inline types shorten the "what columns does this table have?" loop and reduce Slack questions and production debugging via tinker.
• Sequencing decision enabled by v1.1.2. Before this fix, formatters such as Pint import fully qualified class names, so --ci/--test reported every formatted model as outdated once a formatter ran. That is a false-positive generator: teams would have disabled the check within a sprint, or worse, adopted it and lost trust in CI signal. v1.1.2 expands imported class names via the model's imports and namespace before comparison, making the gate trustworthy in real pipelines where Pint is already enforced.
• Supports a "no new tooling without a CI story" policy. Any doc-generation rollout to a large team should be judged on whether it can be gated. This release is what makes the gate viable, so the rollout decision can proceed rather than being deferred.

When to Consider This Package

Adopt when most of the following are true:

• Laravel/Eloquent is the data access layer and models are the shared vocabulary for the domain. This package is purpose-built for that shape and little else.
• The codebase has outgrown tribal knowledge — dozens to hundreds of models, heavy migration churn, or several teams touching the same models.
• Static analysis is already in play (Larastan/PHPStan, Psalm) or is on the roadmap. Generated types are what make those tools useful on Eloquent.
• Pint or an equivalent formatter is already enforced in CI, and you want documentation freshness checked in the same pipeline. Post-v1.1.2, this combination is the intended, working path — the fix specifically addresses formatter-normalized imports.
• You want docs to live next to the code rather than in an external wiki that drifts. Generated PHPDoc on the model is diffable, reviewable, and versioned with the schema.
• The team accepts generated-code churn in PRs and is willing to regenerate as part of the migration workflow.

Look elsewhere or defer when:

• The codebase is small or early-stage. A handful of models does not justify another CI step; a short convention in the contributing guide is cheaper.
• The data layer is not schema-first Eloquent. Heavy use of dynamic attributes, JSON/-> attribute casts, polymorphic or non-Eloquent access, or stored procedures will produce incomplete or misleading annotations, and misleading types are worse than none.
• An IDE-first solution already covers the need. Laravel Idea and barryvdh/laravel-ide-helper overlap substantially. If the goal is editor autocompletion rather than committed, reviewable, CI-checkable docs, the marginal value here is low.
• You cannot tolerate pre-2.0 API churn. This is a 1.x package with a small maintainer surface. Pin the version, and treat upgrades as a reviewed dependency bump rather than an unattended one.
• You need guaranteed vendor support or an SLA. This is community OSS; plan for the maintenance risk explicitly if it becomes load-bearing in CI.

How to Pitch It (Stakeholders)

For executives (one paragraph): Model documentation in a Laravel codebase is normally written by hand and silently rots as migrations land — which is why new engineers take weeks to become productive and why static analysis finds so few real bugs in our models. This package generates that documentation directly from the schema and models, and — critically — lets CI fail when it goes stale, so accuracy stops depending on discipline. The cost is a single artisan command plus one CI step, no runtime dependency, and no vendor contract. The v1.1.2 release fixed the blocker that previously made the CI check unusable alongside our formatter: it was flagging every formatted model as outdated, which would have caused the team to switch the check off. That fix is what makes this safe to adopt, and I recommend piloting it on the highest-churn domain first.

For engineering leadership and platform teams: This is a build-vs-buy decision that resolves to "buy," because the generator is commodity and the maintenance burden of an in-house version is not. Adoption path: add the package as a dev dependency with a pinned constraint, run the generator once to establish a baseline, commit the resulting diffs, then wire --test (or --ci) into the existing Pint/lint stage so documentation drift is caught in the same job that already enforces style. The v1.1.2 change is the enabler for that ordering — class names are now resolved through each model's imports and namespace before comparison, so a Pint-formatted codebase no longer produces universal false positives. Expected outcomes: better Larastan/PHPStan coverage without a typing initiative, faster onboarding on the models that carry the most domain logic, and a documentation standard that enforces itself. Risks to name up front: pre-2.0 version churn, incomplete annotations where dynamic or non-schema attributes are used, and PR noise from regeneration — all manageable with a pinned version, a documented scope for the pilot, and a regeneration step in the migration checklist.

For the immediate team: Run it on one service boundary first, confirm the CI gate is green on a formatted branch, and measure two things over the following month — static-analysis findings touching models, and time-to-first-merged-PR for new joiners. If both move, extend to the rest of the codebase.