Laravel Ignition Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require spatie/laravel-ignition
   

   Ignition auto-discovers and requires no manual configuration for basic usage.

2. First Use Case: Trigger an error in your Laravel app (e.g., 1/0 in a route or controller). Ignition will replace the default Laravel error page with a rich, interactive error page featuring:

   • Stack traces with clickable file links (opens in your IDE).
   • Contextual data (variables, request/response, database queries).
   • AI-powered solutions (if configured with an API key).
   • Copy-to-clipboard functionality for error details.

3. Where to Look First:

   • Error Page: The UI itself guides you with solutions and next steps.
   • Configuration: config/ignition.php (e.g., enabling/disabling features like AI solutions or Flare integration).
   • Documentation: Flare’s Ignition Docs for advanced features.

Implementation Patterns

Daily Workflow Integration

1. Debugging in Development:

   • Trigger Errors: Use throw new \Exception('Test error') or 1/0 in routes/controllers.
   • Navigate Solutions: Ignition suggests fixes (e.g., missing use statements, syntax errors) with clickable "Try this" buttons.
   • Context Inspection: Expand sections like Request, Response, or Database to inspect variables without digging through logs.

2. Production Error Tracking (with Flare):

   • Add your Flare API key to .env:

     FLARE_API_KEY=your_key_here
     

   • Configure ignition.php:

     'enable' => env('APP_ENV') !== 'local',
     'flare' => [
         'enabled' => env('FLARE_API_KEY') !== null,
     ],
     

   • Monitor Errors: Flare aggregates errors, sends notifications, and provides insights (e.g., error frequency, affected users).

3. Customizing Error Pages:

   • Override Views: Publish Ignition’s views and customize them:

     php artisan vendor:publish --tag=ignition-views
     

     Modify files in resources/views/vendor/ignition/.
   • Add Custom Solutions: Extend Ignition’s solution providers (see Implementation Patterns below).

4. Team Collaboration:

   • Share Errors: Use the "Share" button to generate a public link (if Flare is configured).
   • IDE Integration: Click file links in stack traces to open files in PhpStorm/VSCode (requires Flare’s IDE plugin).

5. Testing:

   • Unit Tests: Mock Ignition’s exception handler in tests:

     $this->withoutExceptionHandling(); // Disable Ignition for tests
     

   • Error Scenarios: Test custom solutions by throwing specific exceptions and verifying UI output.

Integration Tips

1. With Livewire:

   • Ignition automatically captures Livewire component errors with stack traces pointing to .blade.php files.
   • Ensure you’re using Livewire 3+ for full support.

2. With Queues/Jobs:

   • Errors in queued jobs are captured and displayed in Ignition. Use the "Retry" button to reprocess failed jobs.

3. With API Requests:

   • Ignition works seamlessly with API routes. For JSON responses, add:

     'api' => [
         'enabled' => true,
         'status_code' => 500,
     ],
     

     to ignition.php to return JSON errors in APIs.

4. With Laravel Forge/Vapor:

   • Deploy Ignition to production (via Forge/Vapor) for consistent error pages across environments.

5. With Custom Exception Handlers:

   • If you extend Laravel’s render() method, ensure Ignition’s middleware runs before your custom logic:

     // app/Http/Kernel.php
     protected $middleware = [
         \Spatie\Ignition\Middleware\RunIgnition::class,
         // ... other middleware
     ];
     

Gotchas and Tips

Pitfalls

1. HTML Data in Logs:

   • Issue: View data (e.g., Blade templates) was previously HTML-dumped into laravel.log.
   • Fix: Updated in v1.7.1/v2.12.0. Ensure you’re on the latest version to avoid log bloat.

2. Middleware Order:

   • Issue: Some middleware (e.g., auth) may not run if Ignition’s middleware is misplaced.
   • Fix: Place \Spatie\Ignition\Middleware\RunIgnition::class first in $middleware (before TrimStrings, ConvertEmptyStringsToNull, etc.).

3. Flare API Key Leaks:

   • Issue: Accidentally exposing the Flare API key in error pages or logs.
   • Fix: Use .env and never hardcode keys. Ignition respects Laravel’s environment variables.

4. Octane/Horizon Compatibility:

   • Issue: Errors in Octane or Horizon may not trigger Ignition.
   • Fix: Ensure ignition.php has:

     'octane' => [
         'enabled' => true,
     ],
     

     And update to v2.5.2+ for fixes.

5. Custom Context Data:

   • Issue: Sensitive data (e.g., passwords) leaking into error contexts.
   • Fix: Use Ignition’s ignition() helper to filter data:

     use Spatie\Ignition\Ignition;
     
     Ignition::configureContext(function ($context) {
         unset($context['request']->headers->all()['authorization']);
     });
     

Debugging Tips

1. Disable Ignition Temporarily:

   • Set ignition.php:

     'enable' => false,
     

   • Or use the CLI flag:

     php artisan serve --ignition=0
     

2. Clear Ignition Cache:

   • If UI behaves unexpectedly, clear compiled views:

     php artisan view:clear
     composer dump-autoload
     

3. Check for Conflicts:

   • Symfony 8/Laravel 13: Ensure you’re on Ignition v2.12.0+.
   • Livewire 4: Requires Ignition v2.10.0+.

4. Log Inspection:

   • Verify errors are logged correctly by checking storage/logs/laravel.log. Ignition should not duplicate logs.

5. Browser Console:

   • Open DevTools (F12) to check for JavaScript errors in Ignition’s UI (e.g., failed API calls to Flare).

Extension Points

1. Custom Solutions:

   • Create a solution provider by extending Spatie\Ignition\Solutions\SolutionProvider:

     namespace App\Providers;
     
     use Spatie\Ignition\Solutions\Solution;
     use Spatie\Ignition\Solutions\SolutionProvider;
     
     class AppSolutionProvider extends SolutionProvider
     {
         public function register(): void
         {
             $this->suggestSolution(
                 \App\Exceptions\CustomException::class,
                 fn () => Solution::make('Fix Custom Exception')
                     ->setDescription('Run `php artisan custom:fix`')
                     ->setCode('<pre>// Add this to AppServiceProvider<br>$this->app->singleton(CustomException::class, fn () => new CustomException());</pre>')
             );
         }
     }
     

   • Register the provider in AppServiceProvider.

2. Custom Context:

   • Add data to error contexts via middleware or the ignition() helper:

     Ignition::configureContext(function ($context) {
         $context['custom_data'] = [
             'user_id' => auth()->id(),
             'action' => request()->route()->getName(),
         ];
     });
     

3. Override Default Solutions:

   • Publish and modify Ignition’s solutions:

     php artisan vendor:publish --tag=ignition-solutions
     

     Edit files in app/Spatie/Ignition/Solutions.

4. AI Solutions:

   • Enable OpenAI integration in ignition.php:

     'ai' => [
         'enabled' => true,
         'open_ai_key' => env('OPENAI_KEY'),
     ],
     

   • Requires an OpenAI API key and may incur costs.

5. Theming:

   • Override CSS/JS by publishing assets:

     php artisan vendor:publish --tag=ignition-assets
     

     Customize files in public/vendor/ignition/.

Pro Tips

1. Error Grouping:

   • Use Flare’s "Group by" feature to categorize errors by exception type or custom tags.

2. **