Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/stevebauman/autodoc-facades
Auto-generate PHP doc annotations for Laravel facades
https://github.com/stevebauman/autodoc-facades
Last synced: 3 days ago
JSON representation
Auto-generate PHP doc annotations for Laravel facades
- Host: GitHub
- URL: https://github.com/stevebauman/autodoc-facades
- Owner: stevebauman
- License: mit
- Created: 2024-01-04T17:27:27.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2024-12-20T00:20:31.000Z (22 days ago)
- Last Synced: 2024-12-31T23:04:34.113Z (10 days ago)
- Language: PHP
- Size: 17.9 MB
- Stars: 91
- Watchers: 3
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Autodoc Facades
A facade documenter for your Laravel application.
---
Autodoc Facades uses the official Laravel [Facade Documenter](https://github.com/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
php artisan autodoc:facades app
```
**Before**:
```php
namespace App\Facades;
/**
* @see \App\Services\ServiceManager
*/
class Service extends Facade
{
// ...
}
```
```php
namespace App\Services;
class ServiceManager
{
public function all(string $param): array
{
// ...
}
}
```
**After**:
```diff
namespace App\Facades;
/**
+* @method static array all(string $param)
+*
* @see \App\Services\ServiceManager
*/
class Service extends Facade
{
// ...
}
```
## Installation
Install via composer:
```bash
composer require --dev stevebauman/autodoc-facades
```
## Usage
Inside the terminal:
```bash
php artisan autodoc:facades {paths} {--only=} {--except=}
```
Inside a Laravel command:
```php
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**:
```php
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:
```php
namespace App\Facades;
use App\Services\ServiceManager;
/**
* @see \App\Services\ServiceManager
*/
class Service extends Facade
{
protected function getFacadeAccessor()
{
return ServiceManager::class
}
}
```
```php
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.
```bash
php artisan autodoc:facades app
```
### Generating annotations in many paths
Space separate paths to generate annotations for facades in those directories:
```bash
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.
```bash
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.
```bash
php artisan autodoc:facades app --except App\Facades\Service
```