Laravel Loom Laravel Package

Product Decisions This Supports

• Architecture visibility as a planning input. Loom statically scans a Laravel codebase and emits a frozen schema 1.0 describing routes, controllers, dispatch sites, events/listeners, models, and (new in v0.4.0) model_events, plus an audited query surface. That gives PMs and tech leads a defensible map of the system for roadmap scoping, module ownership, and "what breaks if we touch this" conversations — without asking engineers to hand-maintain diagrams.
• Build vs. buy on internal tooling. If your team has ever floated "we should build an internal architecture dashboard / dependency map / onboarding wiki generator," this is the buy (or adopt-open-source) option. The frozen schema and MCP surface mean you're integrating against a contract rather than a moving target — a meaningful de-risker versus building bespoke AST tooling.
• AI-assisted engineering investment. The optional laravel/mcp surface plus Boost guidelines and skill (v0.4.0) make the codebase's structure queryable by agents. This is the concrete enabler for decisions like "should we invest in AI coding assistants for this repo, and will they have real context or just vibes?"
• Refactor and migration risk sizing. Dispatch execution-mode recording (sync vs. queued) and closure/route/event-handler coverage improvements let you quantify blast radius before a queue migration, event refactor, or route restructuring — the kind of estimate that usually gets made from memory and is wrong.
• Onboarding and platform-team leverage. Route-file discovery via providers and group-attribute inheritance mean the scan reflects how large apps actually wire themselves, which is precisely the knowledge that lives in two senior engineers' heads today.
• Upgrade-gate planning. Dropping Laravel 11 is a hard prerequisite that belongs in your platform upgrade roadmap before adoption is scheduled.

When to Consider This Package

Consider it when:

• You're on Laravel 12+ (Laravel 11 is no longer supported as of v0.4.0 — this is the gating criterion).
• You have a non-trivial Laravel app — multiple service providers, route files loaded dynamically, event/listener wiring, queued jobs. Small CRUD apps won't return the value.
• You want machine-readable architecture output (JSON schema / MCP) rather than a human-only diagram — i.e., you intend to feed it to dashboards, CI checks, or AI agents.
• You need an onboarding accelerator or a pre-refactor impact map and don't want to staff an internal tooling project.
• You're already in or evaluating the Laravel Boost / MCP ecosystem; the optional-dependency split means you can take the scanner without dragging in Livewire or MCP.

Look elsewhere when:

• You're pinned to Laravel 11 or older, or your upgrade timeline is longer than your patience for a v0.x dependency.
• You need runtime observability (actual production traces, latency, live dispatch volumes). This is static analysis — pair it with APM, don't substitute it.
• Your architecture leans heavily on dynamic dispatch, string-built class names, or container-resolved handlers that static scanning can't follow. Coverage is materially better in v0.4.0 (closure ownership, dispatchIf/Unless, Event facade aliases, inherited handlers) but static analysis has a ceiling.
• You require vendor-backed support, SLAs, or a multi-maintainer bus factor. This is a single-maintainer, pre-1.0 package.
• You need a stable public PHP API. The scanner ADR and @internal tagging on optional-package classes clarify the boundary, but the supported surface is deliberately narrow — treat it as a CLI + schema tool, not a library.

How to Pitch It (Stakeholders)

For executives (one paragraph): Loom is a free, open-source scanner that reads a Laravel codebase and produces a precise, machine-readable map of how it's wired — routes, events, jobs, models, queries. It's the difference between "we think this is what the system does" and a generated artifact anyone can query, including AI assistants. Adoption cost is low (a dev dependency, no runtime footprint), and the v0.4.0 release froze the output schema at 1.0, so what we build on top won't silently break. The trade-offs are honest: it requires Laravel 12+, it's a young v0.x project maintained by one person, and it maps structure rather than live traffic. Recommendation: pilot on one service to measure onboarding and pre-refactor estimation gains before standardizing.

For engineering leads: v0.4.0 is a maturity release, not a feature grab-bag. The scanner now discovers route files loaded by providers and inherits group attributes into them, which closes the biggest real-world coverage gap for large apps — the scanning now matches how the app actually boots. loom:scan gained configurable paths and options, so monorepos and non-standard layouts are workable. Dispatch sites now record execution mode, so you can distinguish synchronous from queued paths when reasoning about a queue migration. Under the hood there was real hygiene work — a Support\Ast facade, a single Fqcn helper, a declarative DispatchRule table, ClassPrimitiveDiscovery with per-primitive specs — which matters less for what it does today and more for whether it's maintainable enough to trust. Two things to note before you install: Laravel 11 support is dropped, and Livewire and laravel/mcp are now optional peer packages — if you want the UI or the agent surface you opt in explicitly, and classes belonging to those optional packages are tagged @internal, so don't build against them.

For the team adopting it: Install as a dev dependency, run loom:scan in CI, and diff the schema between branches to catch unintended architectural drift. Pair it with your APM — Loom tells you what can happen, your traces tell you what does.