Signal Laravel Package

Product Decisions This Supports

• Build vs. buy for architecture observability. This is not a feature you ship to customers — it's a schema you adopt so you can generate the artifacts you keep rebuilding by hand: service catalogs, dependency diagrams, onboarding docs, refactor blast-radius reports. The "buy" is a vocabulary and a pile of PHP attributes; the "build" is a small reflection consumer (an inventory command, ~50 lines). That split is the decision to make: are we willing to own the consumer?
• Roadmap: promote "living architecture docs" from chore to capability. One type attribute per class (Controller, Action, Job, Listener, Service, Repository, Query, Aggregate, ValueObject, …) plus metadata (DependsOn, Emits, ListensTo, SideEffect, Throws, Route, Authorize, Validates, Cached, Deprecated, Internal) produces machine-readable output that is generated from source and therefore cannot silently rot. That is the difference between a wiki page nobody trusts and an artifact you can diff in CI.
• Governance decisions you can encode as merge blockers. DependsOn turns architectural opinions into lint surface: "no Controller may depend on a Repository directly," "every Job must declare a queue," "every Route must carry an Authorize unless tagged public." This converts recurring code-review arguments into a build failure — a process decision, not an engineering one, and one that needs PM sponsorship because it will initially block merges.
• Onboarding and incident response. "What calls this?" and "what breaks if I change this?" are answerable from the inventory rather than from tribal knowledge. Quantify this if you can (time-to-first-PR for new hires, mean time to locate blast radius) — it is the most defensible business case here.
• Agent-assisted documentation at bounded cost. The bundled SKILL.md is written for a coding agent with explicit "do not refactor" instructions, which means annotation can be drafted cheaply per module and reviewed by humans. That changes the cost curve on a documentation initiative from "weeks of senior time" to "review time only."
• Decisions this package does not support — and this is the most important bullet. The public description promises a runtime eventing layer ("define a signal, dispatch it, let listeners pick it up," testable with Laravel's event fakes). The shipped code and the bundled SKILL.md describe an attribute/annotation library with no service provider, no config, and no runtime behaviour. #[Route] does not register routes; #[Authorize] does not authorize; #[Emits] does not dispatch. Do not let a roadmap line item be written against the marketing copy. Confirm which surface you are adopting before any commitment.

When to Consider This Package

Adopt when:

• You have a Laravel monolith or modular app where architecture drift is a recurring, named pain — reviewers arguing about layering, unowned dependencies, or "who dispatches this event?"
• You can fund the consumer. The package alone delivers zero value; a reflection inventory command and (optionally) one CI rule are minimum viable. If nobody owns that, don't start.
• You will accept a single source of truth per concern in a written style guide. #[Route] next to routes/api.php, #[Cached(ttl:) next to cache()->remember(), #[Deprecated] next to @deprecated — PHP won't complain, so your reviewers must. Pick winners up front.
• You can scope adoption in stages: skeleton smoke test → one pilot module → inventory command → one CI rule → widen. A big-bang annotation pass over a monolith will burn the goodwill the pilot needs.
• You are comfortable with vendor risk at this scale. MIT, single maintainer, ~46 stars, zero dependents: removal is find-and-delete, so the downside is contained, but there are no battle-tested integration patterns to copy. If CI starts blocking merges on these rules, budget for vendoring or forking — you don't want your build pipeline pinned to an unmaintained release cadence.

Look elsewhere when:

• You need actual runtime eventing, dispatching, or listener registration → illuminate/events, the router, or queue middleware. This package is the wrong layer.
• You need OpenAPI or a browsable docs site → OpenAPI generators and your existing static site generator. Signal is a schema to feed those, not replace them.
• You want enforced static analysis out of the box → PHPStan, Deptrac, and Laravel architecture tests give you dependency rules today without an annotation pass.
• Your codebase is small, stable, or low-churn — the annotation tax exceeds the informational return.
• You cannot commit to annotation hygiene. Stale #[Throws] or #[Emits] annotations are worse than none because they get trusted. If there is no review checklist item and no periodic sweep, skip it.
• You are evaluating this mid-2026 and the runtime-event surface is still only in the README. Treat the description/code divergence as an open product question, not a documentation bug.

How to Pitch It (Stakeholders)

To executives: This is a low-cost, fully reversible experiment in making our architecture machine-readable. We install a small MIT-licensed annotation vocabulary, spend roughly one engineer-week building a generator that turns it into a live service catalog and dependency report, and pilot it on a single module. Success criteria are concrete: the catalog is generated rather than curated, and one architectural rule is enforced automatically at merge time. Failure costs us an afternoon of uninstall — the annotations are inert and there is no runtime coupling. It is not a platform bet; it is a documentation initiative with a measurable exit.

To engineering: Signal is metadata, not magic. It ships no service provider and no runtime behaviour — attributes are inert until we write a reader, which is about fifty lines of reflection. That's the whole product. What it buys us is a single, consistent vocabulary for describing what a class is and what it touches, written next to the declaration so it can't drift into a wiki. We then generate our architecture docs from source and, once the inventory is trustworthy, promote one or two long-running review arguments into CI rules. Two things to internalize before we start: pin ^1.0.1 (v1.0.0 shipped a broken autoloader specifically for the installed-as-dependency case, which is exactly how we consume it), and read skills/signal/SKILL.md before annotating anything — it is the authoring standard, and inventing a second convention alongside it defeats the purpose. Critically: #[Authorize] and #[Validates] describe checks the code must actually perform. They enforce nothing. We will say that loudly in the style guide, because a new engineer assuming otherwise is a security-shaped hazard, not a documentation nit.