Laravel Brain Laravel Package

Getting Started

Minimal path from zero to first insight:

composer require --dev laramint/laravel-brain
php artisan brain:scan
# → Open the viewer at: http://localhost:8000/_laravel-brain

The service provider is auto-discovered — no registration, no config publish required. Requirements are PHP 8.0+ and Laravel 9–13, so it drops into virtually any maintained project. The scan writes JSON graph files to storage/app/laravel-brain/ and the viewer is served through your existing Laravel routes at /_laravel-brain; there is no second process to manage, which is the main reason this is easier to adopt than a standalone graph tool.

Where to look first: don't start at the project-wide graph — it's overwhelming on anything larger than a toy app. Open the viewer and pick a route node you already understand deeply. Walk its tab: route → middleware → controller → service → model → events/jobs. That single exercise calibrates whether you trust the analyzer's output on your codebase (heavy dynamic dispatch, custom container bindings, or macro-heavy code will show up here as gaps). Only after that should you explore routes you don't know.

First real use case: onboarding to, or inheriting, an unfamiliar area. Pick a legacy route, open its sequence diagram, expand the source viewer on the controller, and read the call chain rather than grepping. Expect 20–40 seconds for a scan on a mid-size project.

If the scan dies on memory, raise the limit — the default is 1024M and the minimum accepted value is also 1024M:

php artisan brain:scan --memory-limit=2G      # or -1 for unlimited

Implementation Patterns

The orientation loop. For any unfamiliar feature: brain:scan → find the route node → sequence diagram (exportable as PNG/Mermaid) → source viewer → then open your editor. This replaces the usual "grep the route name, follow use statements" ritual. Layouts (dagre hierarchical for call chains, cose-bilkent for messy dependency clusters) matter here — hierarchical is the right default for lifecycle tracing.

Pre-refactor impact analysis. Before touching a service, resource, view, or model, locate its node and read inbound edges. This package's differentiator is that it links things most static tools ignore: API resources (UserResource::make(), ::collection(), nested composition), Blade composition (@include, @extends, <x-...>), observers, policies, and broadcast channels. A changed shared partial shows every entry point that reaches it; a changed resource shows every controller using it. That's the "who breaks if I touch this" answer you'd otherwise get by grepping and hoping.

Watch mode during active work. Run php artisan brain:scan --watch --interval=5 in a spare terminal while you implement. Changes confined to app/ re-trace only the affected controllers and merge into the previous graph, so refreshes stay fast. Treat the viewer as a live map of the feature you're building.

AI context handoff — the highest-leverage daily use. The exported context is deterministic (same scan + same node ⇒ byte-identical output), which means you can paste it into an LLM and get reproducible answers, or cache/diff it. Calibrate the budget or you'll silently lose data:

php artisan brain:export-context --node="action::App\Http\Controllers\UserController::index" \
  --budget=8000 --output=/tmp/ctx.md --force

Use --node for a focused call chain (route → middleware → controller → downstream, depth ≤ 3) and --route="GET /users" when you think in HTTP terms. --format=json plus GET /_laravel-brain/api/context lets you script it into whatever agent harness you already use.

Generate AI rules once per scan, and commit them. brain:generate-rules writes CLAUDE.md, .cursor/rules/laravel-brain.mdc, AGENTS.md, and four more, each populated with your real architecture counts, top routes, complexity hotspots, and package lists. Preview with --dry-run, then commit the generated files so the whole team's assistants share the same project context. Re-run after meaningful architectural changes — the files are snapshots, not live.

Health-review cadence (weekly or before a sprint). Scan, then read three things: complexity hotspots (≥16 critical, 10–15 high, 7–9 inspect), fat-class flags (>300 lines or >10 methods on controllers/services), and the DB query section. For DB, hunt two specific patterns: any raw query (DB:: calls bypass model events, observers, and auditing), and the same table appearing across ≥5 unrelated controllers (missing a repository/service boundary). Auto-discover route mode (--auto-discover or LARAVEL_BRAIN_AUTO_DISCOVER_ROUTES=true) is worth switching on temporarily if you need package-registered routes — Filament panels, Livewire, Sanctum — in the graph; default AST mode can't see them.

Route stress test for endpoints you suspect are slow: select the route node, configure concurrency and request count, and read p50/p95/p99 plus status distribution in the sidebar while the path animates. Requires laramint/laravel-stress.

Gotchas and Tips

It is a dev tool — keep it out of production and verify the route isn't exposed. The README frames it as --dev only, but the viewer route is registered by the service provider whenever the package is installed. After installing, run php artisan route:list | grep laravel-brain and confirm it's absent (or gated behind local-only middleware) in your production configuration. Don't ship it in a release image.

Storage permission mismatch is the most common install failure. The web server user and CLI user differ, so brain:scan writes fine but the viewer 500s on read. Fix: chmod -R 775 storage bootstrap/cache. If the command itself isn't found after install, check autoload-dev in composer.json and composer dump-autoload.

--node and --route do not scope the hotspot table. They only change the focal node for the Call Chain section; the full project hotspot list always appears. There is no node-scoped hotspot export via CLI — the browser viewer is the only place to get a per-route or per-category breakdown (including the security issues, which the scan output reports as a single undifferentiated count). Reach for the JSON API when you need the split:

curl -s "http://localhost:8000/_laravel-brain/api/context?format=json" \
  | python3 -c "import sys,json,collections; d=json.load(sys.stdin); \
    c=collections.Counter(i['type'] for n in d['nodes'] \
    for i in n.get('data',{}).get('security',{}).get('issues',[])); \
    [print(v,k) for k,v in c.most_common()]"

Budget truncation is silent and asymmetric. Structural metadata (call chain, hotspots, DB ops) is always included; only source snippets are truncated to fit. But on projects with enough controllers the hotspot table itself gets cut — always override the 6000-token default per the table above.

Known false-positive families in complexity scoring. Filament schema methods (columns(), filters(), form(), table()) score high purely from chained ->when() configuration. Custom query builders do the same. Artisan argument parsing branches legitimately. And high cyclomatic + low line count is frequently a match/switch on an enum — check before flagging. The useful combined signal is cyclomatic × lines; low cyclomatic with ≥150 lines is still a structural smell.

Line numbers drift. Hotspots and source references reflect the last scan. After edits, use grep -n to locate the real position rather than jumping to the reported line — this bites immediately if you scan once and then work for an hour.

Static analysis has honest blind spots. Dynamic dispatch, app()->make() on an interface, and factory-returned jobs can't be resolved; the package flags these as unresolved dispatch rather than silently showing "no impact" — treat those nodes as a to-do to read source. Watch mode also has scope limits: only changes confined to app/ get the cheap merge path. Adding/deleting a file, or editing anything under routes/ or config/, triggers a full rebuild.

Auto-discover mode trades traceability for coverage. You gain package-registered routes but lose source file and line numbers, so the sidebar collapses route grouping into one bucket. Vendor-handler routes are excluded by default (LARAVEL_BRAIN_AUTO_DISCOVER_EXCLUDE_VENDOR=false to include Telescope/Horizon/Ignition noise). Use --auto-discover as a one-off flag rather than flipping config permanently.

Extension point: the JSON is the contract. Everything the viewer does is driven by files in storage/app/laravel-brain/. That means you can gitignore the graph output (it's large and churny) but post-process it for dashboards, diff two scans across branches to prove a refactor reduced complexity, or feed the API into CI. Commit the generated AI rules files and composer.json/composer.lock — not the graph.

Maturity note. 939 stars but zero dependents and a read-only analysis posture: low blast radius, but pin the exact version and read release notes before composer update. The analyzers parse your source with AST tooling, so a major Laravel or Filament upgrade is the most likely source of breakage.