signal

Signal

Signal is a PHP library that turns PHP attributes into living documentation. Annotate your classes and methods with Signal's attributes, then run a single command to generate Markdown and JSON docs that always reflect your actual code.

No more docs that drift. No more manually maintained API references. Signal reads your annotations and writes the documentation for you.

---

Requirements

• PHP 8.5+
• Symfony Console

---

Installation

composer require juststeveking/signal

---

Quick Start

1. Create a signal.json config at your project root:

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

2. Annotate your classes:

use JustSteveKing\Signal\Attributes\Service;
use JustSteveKing\Signal\Attributes\Deprecated;
use JustSteveKing\Signal\Attributes\DependsOn;
use JustSteveKing\Signal\Attributes\Route;
use JustSteveKing\Signal\Attributes\Authorize;
use JustSteveKing\Signal\Attributes\Throws;

#[Service(
    description: 'Handles order processing and payment workflows',
    tags: ['orders', 'payments'],
)]
#[DependsOn(class: PaymentGateway::class, description: 'Required for processing payments')]
#[DependsOn(class: OrderRepository::class)]
final class OrderService
{
    #[Route(method: 'POST', path: '/orders', description: 'Create a new order')]
    #[Authorize(ability: 'orders.create')]
    #[Validates(field: 'items', rules: 'required|array|min:1')]
    #[Validates(field: 'payment_method', rules: 'required|string')]
    #[Emits(event: 'OrderPlaced', description: 'Fired after successful order creation')]
    #[Throws(exception: PaymentFailedException::class, description: 'When payment processing fails')]
    public function store(Request $request): OrderResource
    {
        // ...
    }
}

3. Generate documentation:

php vendor/bin/signal generate

Signal scans your src/ directory, reflects on every annotated class, and writes docs/signal.md and docs/signal.json.

---

Configuration

Key	Type	Description
input	string	Directory to scan (relative to config file)
output.format	string[]	Output formats: markdown, json, or both
output.path	string	Directory to write generated files
exclude	string[]	Paths to skip during scanning

---

Attributes

Signal provides 24 attributes split into three groups: class type attributes that identify what a class is, class metadata attributes that describe relationships and status, and method attributes that document individual methods.

---

Class Type Attributes

These attributes appear on a class declaration and tell Signal what kind of class it is. Each accepts a description string and a tags array.

#[Module]

Top-level application module grouping related functionality.

use JustSteveKing\Signal\Attributes\Module;

#[Module(description: 'Handles everything related to billing', tags: ['billing'])]
final class BillingModule {}

#[Service]

Application or domain service containing business logic.

use JustSteveKing\Signal\Attributes\Service;

#[Service(description: 'Processes subscription renewals', tags: ['subscriptions', 'billing'])]
final class SubscriptionRenewalService {}

#[Repository]

Data access layer class that wraps persistence.

use JustSteveKing\Signal\Attributes\Repository;

#[Repository(description: 'Reads and writes Order records', tags: ['orders', 'persistence'])]
final class OrderRepository {}

#[Action]

Single-purpose action class (use case / interactor).

use JustSteveKing\Signal\Attributes\Action;

#[Action(description: 'Places a new customer order', tags: ['orders'])]
final class PlaceOrderAction {}

#[Controller]

HTTP controller that handles incoming requests.

use JustSteveKing\Signal\Attributes\Controller;

#[Controller(description: 'Manages order CRUD endpoints', tags: ['orders', 'api'])]
final class OrderController {}

#[Event]

Domain event representing something that happened.

use JustSteveKing\Signal\Attributes\Event;

#[Event(description: 'Fired when a customer places an order', tags: ['orders', 'events'])]
final class OrderPlacedEvent {}

#[Listener]

Event listener that reacts to one or more domain events.

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

#[Listener(description: 'Sends a confirmation email after order is placed', tags: ['orders', 'email'])]
#[ListensTo(event: 'OrderPlaced', description: 'Triggers the confirmation email')]
final class SendOrderConfirmationListener {}