Autodoc Facades

A zero-dependencies 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

stevebauman / autodoc-facades