stevebauman / autodoc-facades

Auto-generate PHP doc annotations for Laravel facades

Autodoc Facades

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

autodoc-facades's Issues

[bug] laravel9 Class "Illuminate\Support\Facades\Process" not found

laravel9 Execution error！Process only runs on laravel10, Can you consider an implementation method that is compatible with lower versions?

php artisan autodoc:facades app

   Error 

  Class "Illuminate\Support\Facades\Process" not found

  at vendor/stevebauman/autodoc-facades/src/Commands/DocumentFacades.php:45
     41▕                 fn (string $classname) => ! in_array($classname, $except)
     42▕             );
     43▕         }
     44▕ 
  ➜  45▕         $result = Process::run(sprintf('php -f vendor/bin/facade.php -- %s', $facades->map(
     46▕             fn (string $classname) => str_replace('\\', '\\\\', $classname)
     47▕         )->join(' ')));
     48▕ 
     49▕         $result->successful()

      +13 vendor frames 
  14  artisan:37
      Illuminate\Foundation\Console\Kernel::handle(Object(Symfony\Component\Console\Input\ArgvInput), Object(Symfony\Component\Console\Output\ConsoleOutput))

Useful for decorators too

Hi, I wonder if it wouldn't be possible to extend this package to also be able to generate docblocks on classes that use the decorator pattern (like using the ForwardsCalls trait). I suppose the only real differences are that (1) they don't extend a common class like Facade, and (2) their methods are dynamic, not static.
Would you be interested in a PR that adds an additional autodoc:decorators command?
Or maybe just a common autodoc:generate which uses a publishable config file to determine what to generate.