Autodoc Facades Laravel Package

Technical Evaluation

Architecture fit. stevebauman/autodoc-facades is a narrowly scoped, dev-time code generation utility. It inspects Laravel's facade layer, resolves each facade's underlying accessor, and emits @method PHPDoc annotations so IDEs and static analyzers (PHPStan/Larastan, Psalm) can resolve calls made through facades. It is not a runtime dependency, does not alter application behavior, and introduces no new request-path code. Architecturally it sits alongside tooling like laravel-ide-helper, and its blast radius is limited to generated docblocks and a config file.

Integration feasibility. Very high. It is a standard Composer require-dev install with an artisan command (autodoc:facades) and a publishable config. Integration is a few lines in composer.json scripts or a CI step. There is no service provider wiring to reason about beyond package discovery, no database, no queue, no external services. A single engineer can prove value in an afternoon.

Technical risk. Low but non-zero. The main risks are (1) generated documentation drifting from reality if the command is not re-run after facade or container-binding changes; (2) facade resolution gaps for dynamically bound classes, macros, or custom facades that don't follow the standard getFacadeAccessor contract; (3) overlap/conflict with laravel-ide-helper, which can produce duplicate or contradictory annotations if both write to the same files; (4) sensitivity to Laravel major-version changes in facade internals. None of these are production-availability risks — worst case is a stale or noisy docblock file that fails a static-analysis gate.

Key questions.

• Do we already run laravel-ide-helper, and if so, which tool should own facade annotations to avoid duplication?
• Is PHPStan/Larastan or Psalm already enforced in CI, and at what level? This determines whether the package is a convenience or a hard quality gate.
• Will the generated file be committed to the repo or produced at build time (and gitignored)? That choice drives review noise and drift risk.
• Which Laravel and PHP versions are in the support matrix, and does the package's latest release cover them?
• How many custom/internal facades do we have, and does the config's include/exclude list handle them cleanly?

Integration Approach

Stack fit. Best fit is a Laravel 9+/PHP 8.1+ monolith or modular Laravel app that leans on facades and has adopted (or wants to adopt) static analysis. Poor fit for codebases that avoid facades in favor of constructor injection, or for teams without IDE/static-analysis tooling where generated docblocks deliver no value.

Migration path. Add as require-dev, publish the config, run php artisan autodoc:facades once to generate the annotation file, and diff the result. Review the diff for correctness on a handful of high-traffic facades before committing. Then wire it into a Composer post-update-cmd script or a CI check. No migration of application code is required — this is additive tooling that can be removed by deleting the dev dependency and the generated file.

Compatibility. Verify against the team's exact Laravel and PHP versions, and confirm behavior with PHPStan/Larastan if both are in play. Test with a representative custom facade and at least one macro-heavy facade to confirm resolution works in our specific container setup. Check the license (MIT — no friction) and whether the maintainer's release cadence tracks Laravel majors.

Sequencing. (1) Spike on a branch, measure IDE/PHPStan improvement. (2) Decide commit-vs-generate-at-build. (3) If committing, add a CI drift check that re-runs the command and fails on diff. (4) Roll out to the whole team once the workflow is documented. Keep this behind static-analysis adoption; it pays off most after PHPStan is already in CI.

Operational Impact

Maintenance. Minimal ongoing effort, but the repo now carries a generated artifact with a regeneration obligation. The main recurring cost is the drift check and the occasional config tweak when new facades are added. Upgrades are simple composer update bumps; pin to a minor to avoid surprise regeneration diffs.

Support. Single-maintainer, open-source, MIT. 99 stars is respectable for a niche dev tool but small enough that bus factor is a real consideration. Mitigation: the generated output is plain PHPDoc — if the package is abandoned, the file still works and can be hand-maintained or replaced with laravel-ide-helper. No runtime lock-in.

Scaling. Scales linearly and trivially — generation cost is proportional to facade count, runs in seconds, and is independent of traffic. No production scaling concerns because it never executes in production.

Failure modes.

• Command fails on an unresolvable accessor → CI red on an unrelated change; mitigate with a per-facade exclude list.
• Generated file drifts after facade changes → static analysis silently misses real errors; mitigate with the CI regeneration check.
• Duplicate/conflicting annotations alongside laravel-ide-helper → confusing IDE behavior and false PHPStan results; mitigate by picking one owner per file.
• Laravel major upgrade changes facade internals → transient breakage until the package catches up; pin and test on upgrade branches.

Ramp-up. Near zero for individual engineers — the tool runs automatically or in CI; developers just notice better autocompletion. The onboarding burden falls on the platform/tooling owner: document the regeneration command, the commit-vs-generate decision, and the exclusion policy. Budget roughly half a day for initial setup and CI wiring, then treat it as set-and-forget with the drift check as the only ongoing signal.