stevebauman / autodoc-facades
Auto-generate PHP doc annotations for Laravel facades
Installs: 69 068
Dependents: 5
Suggesters: 0
Security: 0
Stars: 91
Watchers: 3
Forks: 3
Open Issues: 0
Type:project
Requires
- php: ^8.1
- illuminate/support: ^8.0|^9.0|^10.0|^11.0
- phpstan/phpdoc-parser: ^1.28
Requires (Dev)
- laravel/facade-documenter: dev-main
- laravel/pint: ^1.0
- orchestra/testbench: ^6.0|^7.0|^8.0|^9.0
README
A facade documenter for your Laravel application.
Autodoc Facades uses the official Laravel Facade Documenter to easily generate doc annotations for your application's Laravel facades inside your app
directory using the @see
annotation with a single command:
php artisan autodoc:facades app
Before:
namespace App\Facades; /** * @see \App\Services\ServiceManager */ class Service extends Facade { // ... }
namespace App\Services; class ServiceManager { public function all(string $param): array { // ... } }
After:
namespace App\Facades; /** +* @method static array all(string $param) +* * @see \App\Services\ServiceManager */ class Service extends Facade { // ... }
Installation
Install via composer:
composer require --dev stevebauman/autodoc-facades
Usage
Inside the terminal:
php artisan autodoc:facades {paths} {--only=} {--except=}
Inside a Laravel command:
namespace App\Console\Commands; class GenerateFacadeDocs extends Command { // ... public function handle(): int { return $this->call('autodoc:facades', [ 'paths' => ['app'], '--except' => ['...'], '--only' => ['...'], ]); } }
Getting started
To begin, your facades must contain an @see
annotation with the fully-qualified namespace.
It will not resolve short-name classnames of classes that were imported.
For example, this will not work:
namespace App\Facades; use App\Services\ServiceManager; /** * @see ServiceManager */ class Service extends Facade { // ... }
If the underlying class forwards calls to another class, add a @mixin
annotation to the underlying class so it is picked up by the documenter:
namespace App\Facades; use App\Services\ServiceManager; /** * @see \App\Services\ServiceManager */ class Service extends Facade { protected function getFacadeAccessor() { return ServiceManager::class } }
namespace App\Services; use Illuminate\Support\Traits\ForwardsCalls; /** * @mixin \App\Services\SomeClass */ class ServiceManager { use ForwardsCalls; // ... }
Generating annotations in path
To generate doc annotations for all facades in your app
directory, supply "app" as the path:
All paths you provide that do not start with a directory separator will use the commands current working directory as the base path.
php artisan autodoc:facades app
Generating annotations in many paths
Space separate paths to generate annotations for facades in those directories:
php artisan autodoc:facades app/Services/Facades app/Api/Facades
Generating annotations for specific facades
Specify "only" classes to generate annotations only for those given:
You may provide multiple "only" classes by space separating them.
php artisan autodoc:facades app --only App\Facades\Service
Generating annotations for except specific facades
Specify "except" classes to generate annotations for all facades, except for those given:
You may provide multiple "except" classes by space separating them.
php artisan autodoc:facades app --except App\Facades\Service