Signal: Generate PHP Docs From Native Attributes | Mohamed Said [ ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MH.png) Mohamed Said Laravel Backend Engineer ](https://www.msaied.com) [ Home ](https://www.msaied.com) [ Projects ](https://www.msaied.com/projects) [ Articles ](https://www.msaied.com/articles) [ Certificates ](https://www.msaied.com/certificates) [ Contact ](https://www.msaied.com#contact-section) [ ](https://github.com/EG-Mohamed) [ Home ](https://www.msaied.com) [ Projects ](https://www.msaied.com/projects) [ Articles ](https://www.msaied.com/articles) [ Certificates ](https://www.msaied.com/certificates) [ Contact ](https://www.msaied.com#contact-section) [ home ](https://www.msaied.com) [ articles ](https://www.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://www.msaied.com/articles?category=composer-pacakge) [ PHP ](https://www.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%2Fwww.msaied.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%2Fwww.msaied.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://www.msaied.com/articles) [ ![Filament v5 Preview: Schema Unification, Performance Shifts, and How to Prepare](https://cdn.msaied.com/340/1a05ca68637b898b676efb66f22e627f.png) filament laravel php ### Filament v5 Preview: Schema Unification, Performance Shifts, and How to Prepare Filament v5 is reshaping how panels, forms, and tables are composed. This deep-dive covers the confirmed archi... ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said 1 Jul 2026 4 min read Read ](https://www.msaied.com/articles/filament-v5-preview-schema-unification-performance-shifts-and-how-to-prepare) [ ![Laravel 13: New Features, Helpers, and Practical Upgrade Notes](https://cdn.msaied.com/339/58c4fa6fe9b6d25a2dac17c621b6f4c6.png) laravel laravel-13 upgrade ### Laravel 13: New Features, Helpers, and Practical Upgrade Notes Laravel 13 ships with async-first defaults, a leaner bootstrapping layer, and several quality-of-life helpers.... ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said 1 Jul 2026 3 min read Read ](https://www.msaied.com/articles/laravel-13-new-features-helpers-and-practical-upgrade-notes) [ ![Laravel 12: Structured Route Files, Slim Skeletons, and the New Application Bootstrapping](https://cdn.msaied.com/337/05b39d16d0f88a5fb94d0cf74049b88b.png) laravel laravel-12 upgrade ### Laravel 12: Structured Route Files, Slim Skeletons, and the New Application Bootstrapping Laravel 12 ships with a leaner skeleton, first-class route file organisation, and a revised application bootst... ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said 1 Jul 2026 3 min read Read ](https://www.msaied.com/articles/laravel-12-structured-route-files-slim-skeletons-and-the-new-application-bootstrapping) [ ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MH.png) Mohamed Said Laravel Backend Engineer ](https://www.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://www.msaied.com) - [Projects](https://www.msaied.com/projects) - [Articles](https://www.msaied.com/articles) - [Certificates](https://www.msaied.com/certificates) - [Contact](https://www.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)