Autodoc Facades Laravel Package

Getting Started

Install it as a dev dependency — it's a build-time annotation generator, not a runtime service:

composer require stevebauman/autodoc-facades --dev

The service provider is auto-discovered. Confirm the generator command is registered (php artisan list | grep autodoc) and run it once against a booted app:

php artisan autodoc:facades

The command walks every facade, resolves the class behind getFacadeAccessor() out of the container, reflects its public methods, and emits @method static ... docblocks into the package's generated annotations file. The command's console output tells you the output path; publish the config (php artisan vendor:publish) if you want to change it. Make sure your IDE indexes that file — in PhpStorm, right-click → Mark as Plain Text is wrong; you want it inside the project and not excluded from indexing.

First use case: you've written App\Facades\Reporting proxying App\Services\ReportingService. Before generating, Reporting::generate($user) shows as an undefined method with no parameter hints. After generating and reindexing, static calls autocomplete with full signatures and return types, and PHPStan/Larastan stops treating the result as mixed. That single win — typed static facade calls — is the entire reason to install it.

Implementation Patterns

Target your own facades, not Laravel's. The framework's facades already have shipped docblocks and are covered by barryvdh/laravel-ide-helper. Scope this package to App\Facades\* via its include/exclude config so the generated file stays small and the run stays fast.

Hook it into Composer. Add the command to post-autoload-dump so annotations regenerate on every composer install, update, and dump-autoload:

"scripts": {
    "post-autoload-dump": ["@php artisan autodoc:facades"]
}

Keep the output deterministic and either commit the generated file (zero-friction onboarding, stable static analysis) or gitignore it and regenerate in CI before running PHPStan.

CI drift check. Generate in CI and git diff --exit-code the output file. When someone adds a public method to the underlying service but forgets to regenerate, the build fails instead of silently degrading IDE support for the whole team.

Write signatures on the service class, not the facade. Annotations are only as good as what reflection sees. Real parameter types, real return types, and nullable/defaulted params on ReportingService propagate directly. Docblock-only typing on the service yields weaker output than native hints.

Facade over an interface? Bind the concrete implementation in a service provider. The generator documents whatever the app's default binding resolves to — which is fine, as long as that binding is a concrete, reflectable class rather than a closure returning a mock or a decorated proxy.

Pair with Larastan. The emitted @method lines let PHPStan understand facade return types, turning a codebase full of mixed into analyzable code without hand-written stubs.

Gotchas and Tips

• Unresolvable accessors produce nothing. If getFacadeAccessor() returns an alias that isn't bound, or a binding that resolves to something non-reflectable, the facade gets skipped. Verify each accessor resolves to a concrete class.
• Macros are invisible. Anything routed through __call/Macroable, or methods added dynamically at runtime, won't appear. Add manual @method lines or @mixin for those.
• Config-driven drivers fool it. If the service is resolved from something like config('services.reports.driver'), the generator only documents the currently configured driver. Document the interface or generate per-environment.
• $this/static return docblocks can be emitted literally and confuse older IDE plugins. Skim the generated file for @return $this artifacts after the first run.
• Don't hand-edit the output. Regeneration overwrites it silently. If you need extra annotations, put them on the underlying class or extend the generator.
• Changing the output path means updating .gitignore, IDE include paths, and PHPStan's scanFiles in lockstep — easy to forget one.
• Stale IDE caches are the #1 "it didn't work" cause. Run Invalidate Caches / Restart and verify the file is indexed before debugging the package itself.
• Missing facade? Check the exclude config first, then confirm the accessor returns a string, then run the command verbosely and read the per-facade output.
• Keep it out of production. require-dev plus a guarded composer script; there's no reason to generate annotations during a deploy.