Laravel Brain Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require --dev laramint/laravel-brain
   

   No manual configuration or service provider registration is needed.

2. First Scan

   php artisan brain:scan
   

   This generates a graph JSON file in storage/app/laravel-brain/ and outputs the URL to access the viewer:

   Done! Open the viewer at: http://localhost:8000/_laravel-brain
   

3. Access the Viewer Navigate to /_laravel-brain in your browser while running php artisan serve or your Laravel application server.

First Use Case

Understand a Route Flow

• Open the viewer and locate a route (e.g., GET /users).
• Click the node to inspect its call chain, including middleware, controller actions, services, and models.
• Use the Sequence Diagram (SVG) to visualize the full request lifecycle.

Implementation Patterns

Daily Workflows

1. Code Review & Onboarding

   • Run php artisan brain:scan after major changes or when onboarding new developers.
   • Use the Route Stress Test feature to validate performance-critical endpoints.

2. Debugging

   • Identify fat classes (controllers/services with >300 lines or >10 methods) via the Cyclomatic Complexity highlights.
   • Trace unexpected job/event dispatches by following edges from controller actions.

3. Architecture Documentation

   • Export AI context for a node (🤖 button) and share it with team members or AI assistants.
   • Generate AI rules files (php artisan brain:generate-rules) to populate coding guidelines for tools like GitHub Copilot or Cursor.

4. Filament Development

   • Discover and trace Filament panels, resources, and pages alongside traditional routes.
   • Use the Method Flowchart to visualize logic within Filament page methods.

Integration Tips

• Watch Mode for Live Development

  php artisan brain:scan --watch --interval=5
  

  Auto-rescans on PHP file changes, keeping the graph up-to-date without manual triggers.

• Memory Management For large codebases, adjust the memory limit:

  php artisan brain:scan --memory-limit=2G
  

• Auto-Discover Routes Enable auto-discovery for programmatically registered routes (e.g., Filament, Sanctum):

  php artisan brain:scan --auto-discover
  

  Or configure it in .env:

  LARAVEL_BRAIN_AUTO_DISCOVER_ROUTES=true
  

• Export Context for AI Generate deterministic context for any node via:

  php artisan brain:export-context --route="GET /users" --output=/tmp/context.md
  

  Or use the API:

  GET /_laravel-brain/api/context?route=GET+/users&format=json
  

• Stress Testing Test route performance directly from the graph:

  • Select a route node → Stress Test tab.
  • Configure concurrency, headers, and timeout.
  • Monitor timing percentiles and throughput in real-time.

Gotchas and Tips

Pitfalls

1. Auto-Discover Mode Limitations

   • Routes discovered via Route::getRoutes() lack source file/line metadata.
   • Use the default AST mode if file/line grouping is critical.

2. Memory Constraints

   • Large codebases may hit PHP memory limits. Monitor and adjust --memory-limit as needed.
   • Avoid --memory-limit=-1 (unlimited) in CI/CD unless necessary.

3. Vendor Route Exclusion

   • By default, routes handled by vendor/ classes (e.g., Telescope) are excluded.
   • Disable exclusion with:

     LARAVEL_BRAIN_AUTO_DISCOVER_EXCLUDE_VENDOR=false
     

4. Filament Auto-Discovery

   • Ensure Filament is installed (composer require filament/filament) for panel/resource tracing.
   • Auto-discovered Filament resources may not appear if ->discoverResources() is misconfigured.

5. Watch Mode Stability

   • Long-running scans may cause timeouts in watch mode. Reduce --interval for faster feedback.

Debugging Tips

• Clear Old Scans Delete storage/app/laravel-brain/ to force a fresh scan if the graph appears stale.

• Check Scan Logs Run with --verbose for detailed tracing:

  php artisan brain:scan --verbose
  

• Isolate Nodes Use the Breadth-First layout to focus on a specific route’s call chain.

• Query Tracing Filter nodes by type (e.g., Model) to locate DB-heavy operations.

Extension Points

1. Custom Node Styling Override node colors or shapes by extending the BrainController or modifying the React SPA (located in vendor/laramint/laravel-brain/resources/js).

2. Additional Analyzers Extend the scanner by adding a custom analyzer (e.g., for laravel-nova or livewire components) by implementing the AnalyzerInterface.

3. API Hooks Use the /_laravel-brain/api/context endpoint to build custom integrations (e.g., CI/CD reports or documentation generators).

4. Graph Layouts Experiment with layouts (e.g., Circle, Grid) via the viewer’s layout dropdown to optimize readability for specific use cases.

Performance Quirks

• Large Graphs Complex applications may slow down the viewer. Use the Force-Directed layout for better performance with dense graphs.

• Stress Test Overhead Concurrent requests during stress tests may impact your local machine. Limit concurrency for testing:

  php artisan brain:stress-test --concurrency=5
  

• Watch Mode Polling High --interval values (e.g., 1) may cause excessive rescans. Balance responsiveness with resource usage.