---
title: "Signal - бібліотека для генерації документації з PHP-атрибутів"
url: https://laravelukraine.com/blog/signal-biblioteka-dlia-generaciyi-dokumentaciyi-z-php-atributiv
author: "Олексій Бабінцев"
date: 2026-06-27
source: https://laravel-news.com/turn-php-attributes-into-docs-with-signal?utm_medium=feed&utm_source=feedpress.me&utm_campaign=Feed%3A+laravelnews
---

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

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

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

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

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

```php
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]` позначають класи, до яких викликачі повинні ставитись обережно:

```php
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]` для помітної роботи на кшталт відправки пошти або запису в чергу.

```php
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` у корені вашого проекту. Він вказує генератору, яку директорію сканувати, які формати писати, куди їх розміщувати і які шляхи пропускати:

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

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

```bash
php vendor/bin/signal generate
```

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

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

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

```bash
composer require juststeveking/signal
```

Ви можете ознайомитись із вихідним кодом і повним списком атрибутів на [GitHub](https://github.com/JustSteveKing/signal).