Signal - бібліотека для генерації документації з PHP-атрибутів

Signal - це PHP-бібліотека від Стіва Макдугала, яка зчитує атрибути, розміщені на класах і методах, і генерує з них документацію. Ідея полягає в тому, щоб тримати API-довідку в тому самому місці, де знаходиться код, який вона описує. Так документація змінюється разом із кодом замість того, щоб застарівати в окремому файлі. Бібліотека вимагає PHP 8.5 та Symfony Console і розповсюджується під ліцензією MIT.

Бібліотека постачається з 24 атрибутами, розділеними на три групи: атрибути, що позначають тип класу, атрибути, які фіксують зв'язки та статус класу, та атрибути для документування окремих методів. Ви анотуєте свій код, запускаєте одну команду й отримуєте Markdown для людей та JSON для інструментів.

Позначення типу класу

Перша група атрибутів описує роль, яку клас виконує у вашому застосунку. Їх 13, і вони охоплюють поширені будівельні блоки: #[Module], #[Service], #[Repository], #[Action], #[Controller], #[Event], #[Listener], #[Middleware], #[Job], #[Command], #[Query], #[Aggregate] та #[ValueObject]. Кожен приймає необов'язковий опис і список тегів:

use JustSteveKing\Signal\Attributes\Service;

#[Service(
    description: 'Issues and revokes API tokens for authenticated users',
    tags: ['auth', 'tokens'],
)]
final class TokenService
{
    // ...
}

Коли Signal генерує вихідні дані, він групує класи за цими типами, тому всі контролери потрапляють в один розділ, а всі сервіси - в інший.

Фіксація зв'язків і статусу

Друга група документує, як клас пов'язаний з рештою системи і на якому етапі життєвого циклу він знаходиться. #[DependsOn] фіксує співробітника (collaborator), #[ListensTo] прив'язує слухача до події, а #[Deprecated] і #[Internal] позначають класи, до яких викликачі повинні ставитись обережно:

use JustSteveKing\Signal\Attributes\Listener;
use JustSteveKing\Signal\Attributes\ListensTo;
use JustSteveKing\Signal\Attributes\DependsOn;

#[Listener(description: 'Sends a welcome email after registration')]
#[ListensTo(event: UserRegistered::class)]
#[DependsOn(class: MailService::class)]
final class SendWelcomeEmail
{
    // ...
}

Ці зв'язки - той тип деталей, який зазвичай зберігається в чиїйсь голові або на діаграмі, яку ніхто не оновлює. Розміщення їх поруч із класом робить їх достовірними.

Документування методів

Третя група описує, що роблять окремі методи. #[Route] фіксує HTTP-метод і шлях, #[Authorize] вказує на здатність (ability), яка потрібна викликачу, #[Validates] захоплює правила валідації поле за полем, а #[Cached] записує TTL. Ще три атрибути документують поведінку, яку сама сигнатура методу не розкриває: #[Emits] для подій, які метод відправляє, #[Throws] для винятків, які він може викинути, та #[SideEffect] для помітної роботи на кшталт відправки пошти або запису в чергу.

use JustSteveKing\Signal\Attributes\Route;
use JustSteveKing\Signal\Attributes\Authorize;
use JustSteveKing\Signal\Attributes\Validates;
use JustSteveKing\Signal\Attributes\Emits;
use JustSteveKing\Signal\Attributes\Throws;
use JustSteveKing\Signal\Attributes\SideEffect;

#[Route(method: 'POST', path: '/api/subscriptions', description: 'Start a subscription')]
#[Authorize(ability: 'subscriptions.create')]
#[Validates(field: 'plan', rules: 'required|in:monthly,yearly')]
#[Emits(event: 'SubscriptionStarted')]
#[SideEffect(description: 'Charges the customer through the payment gateway', tags: ['billing'])]
#[Throws(exception: PaymentFailedException::class, description: 'If the gateway rejects the charge')]
public function store(Request $request): JsonResponse
{
    // ...
}

Атрибути #[SideEffect] і #[Throws] варто виділити окремо, бо вони документують речі, які читач не може вивести з типу повернення. Знання про те, що метод списує кошти з картки або може викинути PaymentFailedException, - це той тип фактів, який інакше проявляється лише тоді, коли щось ламається.

Конфігурація та вихідні дані

Signal зчитує файл signal.json у корені вашого проекту. Він вказує генератору, яку директорію сканувати, які формати писати, куди їх розміщувати і які шляхи пропускати:

{
    "input": "src/",
    "output": {
        "format": ["markdown", "json"],
        "path": "docs/"
    },
    "exclude": [
        "src/Attributes/"
    ]
}

Маючи це налаштування, одна команда генерує документацію:

php vendor/bin/signal generate

Вихідний Markdown організовано за типом класу зі змістом, а JSON містить ті самі метадані у формі, яку можуть читати інші інструменти. Це робить його відправною точкою для таких речей, як генерація OpenAPI-опису або живлення внутрішнього каталогу сервісів.

Встановлення

Встановіть бібліотеку через Composer:

composer require juststeveking/signal

Ви можете ознайомитись із вихідним кодом і повним списком атрибутів на GitHub.