stevebauman/autodoc-facades

Auto-generate PHP doc annotations for Laravel facades

v1.2.2 2024-11-19 00:21 UTC

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

MIT

• Steve Bauman

• document
• facade
• facades
• annotate
• autodoc

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