Ignition Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require spatie/ignition
   

   For Laravel, use spatie/laravel-ignition instead.

2. Basic Registration: Add this to your bootstrap file (e.g., bootstrap/app.php in Laravel):

   use Spatie\Ignition\Ignition;
   
   Ignition::make()->register();
   

3. First Use Case: Throw an exception in a route/controller:

   Route::get('/test-error', function () {
       throw new \Exception('Test error for Ignition');
   });
   

   Visit /test-error to see the Ignition error page.

Implementation Patterns

Core Workflows

1. Environment-Specific Configuration:

   Ignition::make()
       ->shouldDisplayException(app()->environment('local'))
       ->register();
   

2. Dark Mode:

   Ignition::make()
       ->setTheme('dark')
       ->register();
   

3. Custom Application Path:

   Ignition::make()
       ->applicationPath(base_path())
       ->register();
   

Advanced Patterns

1. Solution Providers: Register custom solutions for exceptions:

   Ignition::make()
       ->addSolutionProviders([
           \App\Providers\CustomSolutionProvider::class,
       ])
       ->register();
   

2. AI-Powered Solutions:

   $aiProvider = new \Spatie\Ignition\Solutions\OpenAi\OpenAiSolutionProvider(config('services.openai.key'));
   Ignition::make()
       ->addSolutionProviders([$aiProvider])
       ->register();
   

3. Flare Integration:

   Ignition::make()
       ->runningInProductionEnvironment(app()->environment('production'))
       ->sendToFlare(config('services.flare.key'))
       ->configureFlare(function ($flare) {
           $flare->context('User', auth()->id());
       })
       ->register();
   

Integration Tips

• Laravel: Use spatie/laravel-ignition for seamless integration with Laravel’s exception handling.
• Middleware: Extend Ignition’s functionality by creating middleware to modify exceptions before they reach Ignition.
• Testing: Use Ignition::fake() in tests to mock error pages.

Gotchas and Tips

Pitfalls

1. Production Exposure:

   • Ignition should never be enabled in production. Always wrap registration in environment checks:

     if (!app()->environment('production')) {
         Ignition::make()->register();
     }
     

2. Sensitive Data:

   • Avoid exposing sensitive data (e.g., API keys, passwords) in error traces. Use censorRequestBodyFields for Flare:

     ->configureFlare(function ($flare) {
         $flare->censorRequestBodyFields(['password', 'api_key']);
     })
     

3. Performance Overhead:

   • AI-powered solutions introduce network calls. Cache responses to avoid repeated API calls:

     $aiProvider->useCache(app('cache'), 3600); // Cache for 1 hour
     

Debugging Tips

1. Disable Ignition Temporarily:

   • Use Ignition::fake() in tests or override the shouldDisplayException method to bypass Ignition during debugging.

2. Clear Cache:

   • If Ignition’s UI appears broken, clear Laravel’s view cache:

     php artisan view:clear
     

3. Check for Conflicts:

   • Ensure no other exception handlers (e.g., App\Exceptions\Handler) are interfering with Ignition’s registration.

Extension Points

1. Custom Solutions:

   • Implement ProvidesSolution for exceptions or HasSolutionsForThrowable for dynamic solutions.

2. Flare Middleware:

   • Add custom logic to Flare reports via FlareMiddleware:

     class LogMiddleware implements \Spatie\FlareClient\FlareMiddleware\FlareMiddleware {
         public function handle($report, \Closure $next) {
             \Log::error($report->getMessage());
             return $next($report);
         }
     }
     

3. UI Customization:

   • Override Ignition’s Blade views in resources/views/vendor/ignition/ for theming.

4. Localization:

   • Extend Ignition’s translations by publishing and overriding its language files:

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