Signal: Generate PHP Docs From Native Attributes | Mohamed Said [ ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MH.png) Mohamed Said Laravel Backend Engineer ](https://msaied.com) [ Home ](https://msaied.com) [ Projects ](https://msaied.com/projects) [ Articles ](https://msaied.com/articles) [ Certificates ](https://msaied.com/certificates) [ Contact ](https://msaied.com#contact-section) [ ](https://github.com/EG-Mohamed) [ Home ](https://msaied.com) [ Projects ](https://msaied.com/projects) [ Articles ](https://msaied.com/articles) [ Certificates ](https://msaied.com/certificates) [ Contact ](https://msaied.com#contact-section) [ home ](https://msaied.com) [ articles ](https://msaied.com/articles) Turn PHP Attributes Into Docs With Signal On this page 1. [ What Is Signal? ](#what-is-signal) 2. [ Three Groups of Attributes ](#three-groups-of-attributes) 3. [ 1. Labelling What a Class Is ](#1-labelling-what-a-class-is) 4. [ 2. Recording Relationships and Status ](#2-recording-relationships-and-status) 5. [ 3. Documenting Methods ](#3-documenting-methods) 6. [ Configuration and Output ](#configuration-and-output) 7. [ Installation ](#installation) 8. [ Key Takeaways ](#key-takeaways) ![Turn PHP Attributes Into Docs With Signal](https://cdn.msaied.com/300/6d30cd7b1adb545febfc5d4050778760.png) [ Composer Pacakge ](https://msaied.com/articles?category=composer-pacakge) [ PHP ](https://msaied.com/articles?category=php) #PHP #PHP Attributes #Documentation #Laravel Packages #Open Source #Developer Tools Turn PHP Attributes Into Docs With Signal =========================================== 26 Jun 2026 3 min read ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said Table of contents 1. [ 01 What Is Signal? ](#what-is-signal) 2. [ 02 Three Groups of Attributes ](#three-groups-of-attributes) 3. [ 03 1. Labelling What a Class Is ](#1-labelling-what-a-class-is) 4. [ 04 2. Recording Relationships and Status ](#2-recording-relationships-and-status) 5. [ 05 3. Documenting Methods ](#3-documenting-methods) 6. [ 06 Configuration and Output ](#configuration-and-output) 7. [ 07 Installation ](#installation) 8. [ 08 Key Takeaways ](#key-takeaways) What Is Signal? --------------- [Signal](https://github.com/JustSteveKing/signal) is an open-source PHP library by Steve McDougall that turns native PHP 8.x attributes into living documentation. Instead of maintaining a separate wiki or API reference that drifts out of date, you annotate your classes and methods directly, run one CLI command, and get back Markdown for humans and JSON for tooling. It requires **PHP 8.5** and Symfony Console, and is distributed under the MIT license. Three Groups of Attributes -------------------------- Signal ships **24 attributes** organised into three logical groups. ### 1. Labelling What a Class Is Thirteen attributes describe the architectural role of a class: `#[Module]`, `#[Service]`, `#[Repository]`, `#[Action]`, `#[Controller]`, `#[Event]`, `#[Listener]`, `#[Middleware]`, `#[Job]`, `#[Command]`, `#[Query]`, `#[Aggregate]`, and `#[ValueObject]`. Each accepts an optional `description` and a `tags` array. ```php use JustSteveKing\Signal\Attributes\Service; #[Service( description: 'Issues and revokes API tokens for authenticated users', tags: ['auth', 'tokens'], )] final class TokenService { // ... } ``` The generator groups output by these types, so every controller lands in one section and every service in another. ### 2. Recording Relationships and Status A second group documents how a class connects to the rest of the system. `#[DependsOn]` records a collaborator, `#[ListensTo]` ties a listener to an event, and `#[Deprecated]` / `#[Internal]` flag classes that callers should treat with care. ```php #[Listener(description: 'Sends a welcome email after registration')] #[ListensTo(event: UserRegistered::class)] #[DependsOn(class: MailService::class)] final class SendWelcomeEmail { // ... } ``` This is the kind of relationship detail that usually lives only in someone's head or in a diagram nobody updates. ### 3. Documenting Methods The third group targets individual methods. `#[Route]` records an HTTP method and path, `#[Authorize]` notes the required ability, `#[Validates]` captures field-level rules, and `#[Cached]` records a TTL. Three more attributes surface behaviour invisible in a method signature: `#[Emits]` for dispatched events, `#[Throws]` for exceptions, and `#[SideEffect]` for observable work like charging a card or writing to a queue. ```php #[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]` and `#[Throws]` are particularly valuable — they document facts a return type alone cannot convey. Configuration and Output ------------------------ Signal reads a `signal.json` file at the project root: ```json { "input": "src/", "output": { "format": ["markdown", "json"], "path": "docs/" }, "exclude": [ "src/Attributes/" ] } ``` Then generate your docs with a single command: ```bash php vendor/bin/signal generate ``` The Markdown output includes a table of contents organised by class type. The JSON output carries the same metadata in a machine-readable form, making it a useful starting point for generating OpenAPI descriptions or feeding an internal service catalogue. Installation ------------ ```bash composer require juststeveking/signal ``` Key Takeaways ------------- - Signal uses **native PHP attributes** — no docblock parsing, no external annotation syntax. - **24 attributes** cover class roles, inter-class relationships, and method-level behaviour. - Outputs both **Markdown** (human-readable) and **JSON** (machine-readable) from one command. - Keeping docs next to code means they update when the code updates, reducing documentation drift. - Requires PHP 8.5 and Symfony Console; MIT licensed. - The JSON output can seed OpenAPI specs or internal service catalogues. --- Source: [Turn PHP Attributes Into Docs With Signal — Laravel News](https://laravel-news.com/turn-php-attributes-into-docs-with-signal) Found this useful? [ ](https://twitter.com/intent/tweet?url=https%3A%2F%2Fmsaied.com%2Farticles%2Fturn-php-attributes-into-docs-with-signal&text=Turn+PHP+Attributes+Into+Docs+With+Signal) [ ](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fmsaied.com%2Farticles%2Fturn-php-attributes-into-docs-with-signal) Frequently Asked Questions ---------------------------- 3 questions Q01 What PHP version does Signal require? Signal requires PHP 8.5 and Symfony Console. It is distributed under the MIT license. Q02 What output formats does Signal produce? Signal generates both Markdown (organised by class type with a table of contents) and JSON (machine-readable metadata suitable for OpenAPI generation or service catalogues). Q03 How do you run Signal to generate documentation? After adding a signal.json configuration file to your project root, run `php vendor/bin/signal generate`. Signal scans the configured input directory and writes docs to the configured output path. Continue reading More Articles --------------- [ View all ](https://msaied.com/articles) [ ![Help Make Filament Faster: Beta Versions of v4 and v5 Now Available for Testing](https://cdn.msaied.com/299/b7163ad1d319ebdd0e7128cc976053bf.png) Filament Laravel Performance ### Help Make Filament Faster: Beta Versions of v4 and v5 Now Available for Testing The Filament team has released performance-focused beta versions of both v4 and v5. Install them today, test i... ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said 26 Jun 2026 3 min read Read ](https://msaied.com/articles/help-make-filament-faster-beta-versions-of-v4-and-v5-now-available-for-testing) [ ![Filament v4 Schema-Based Forms, Infolists, and the Unified Schema API](https://cdn.msaied.com/297/6eb3a7aaf7148fd21116eea870bd004e.png) filament laravel filament-v4 ### Filament v4 Schema-Based Forms, Infolists, and the Unified Schema API Filament v4 replaces scattered form and infolist definitions with a single Schema API. Learn how unified schem... ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said 26 Jun 2026 3 min read Read ](https://msaied.com/articles/filament-v4-schema-based-forms-infolists-and-the-unified-schema-api-1) [ ![Laravel Pipeline Pattern: Building Custom Pipelines Beyond Middleware](https://cdn.msaied.com/296/afbac95c7f4aac1cee83eb2c87541369.png) laravel pipeline clean-architecture ### Laravel Pipeline Pattern: Building Custom Pipelines Beyond Middleware The Pipeline pattern in Laravel is far more powerful than middleware alone. Learn how to build typed, composab... ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said 26 Jun 2026 4 min read Read ](https://msaied.com/articles/laravel-pipeline-pattern-building-custom-pipelines-beyond-middleware-1) [ ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MH.png) Mohamed Said Laravel Backend Engineer ](https://msaied.com)Senior Backend Engineer specializing in Laravel, scalable SaaS platforms, APIs, and cloud infrastructure. I build secure, high-performance web applications that help businesses grow. Explore - [Home](https://msaied.com) - [Projects](https://msaied.com/projects) - [Articles](https://msaied.com/articles) - [Certificates](https://msaied.com/certificates) - [Contact](https://msaied.com#contact-section) Connect - [ hello@msaied.com ](mailto:hello@msaied.com) - [ +20 109 461 9204 ](tel:+201094619204) © 2026 Mohamed Said. All rights reserved. [ ](https://github.com/EG-Mohamed) [ ](https://www.linkedin.com/in/msaiedm/) [ ](https://wa.me/201094619204) [ ](mailto:hello@msaied.com) [ ](https://drive.google.com/file/u/0/d/1MF20IPRJyzfy32mhEutjL5EpSls0w2Q8/view)