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 or controller:

   throw new \Exception('Test error for Ignition');
   

   Visit the URL in your browser to see the Ignition error page.

Implementation Patterns

Core Workflow

1. Error Handling: Ignition automatically captures uncaught exceptions and renders them in a user-friendly UI. No manual error handler setup is required.

2. Environment-Specific Behavior:

   • Development: Display Ignition UI with detailed stack traces.
   • Production: Optionally hide Ignition and send errors to Flare (see below).

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

3. Integration with Laravel:

   • Laravel-specific features (e.g., route/environment detection) are handled by spatie/laravel-ignition. Use this package for Laravel projects.
   • For non-Laravel PHP apps, use the base spatie/ignition package.

4. Flare Integration: Send errors to Flare for monitoring in production:

   Ignition::make()
       ->runningInProductionEnvironment(app()->environment('production'))
       ->sendToFlare(config('services.flare.key'))
       ->register();
   

Advanced Patterns

1. Custom Solutions:

   • Per-Exception Solutions: Implement ProvidesSolution in custom exceptions:

     class CustomException extends \Exception implements \Spatie\Ignition\Contracts\ProvidesSolution {
         public function getSolution(): \Spatie\Ignition\Contracts\Solution {
             return new class implements \Spatie\Ignition\Contracts\Solution {
                 public function getSolutionTitle(): string { return 'Fix the config'; }
                 public function getSolutionDescription(): string { return 'Update `config/app.php`'; }
                 public function getDocumentationLinks(): array { return []; }
             };
         }
     }
     

   • Solution Providers: Register providers to handle multiple exceptions:

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

2. AI-Powered Solutions: Use OpenAI to suggest fixes (requires openai-php/client):

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

3. Flare Customization:

   • Add context or middleware:

     Ignition::make()
         ->configureFlare(function (\Spatie\FlareClient\Flare $flare) {
             $flare->context('User', auth()->id());
             $flare->registerMiddleware(\App\FlareMiddleware::class);
         })
         ->register();
     

   • Censor sensitive data:

     $flare->censorRequestBodyFields(['password', 'token']);
     

4. Theming: Switch between light/dark mode:

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

Gotchas and Tips

Common Pitfalls

1. Production Leaks:

   • Ignition should not be enabled in production unless explicitly configured to send errors to Flare.
   • Always use shouldDisplayException(false) in production:

     Ignition::make()
         ->shouldDisplayException(false)
         ->runningInProductionEnvironment(true)
         ->sendToFlare(config('services.flare.key'))
         ->register();
     

2. Path Trimming:

   • Ignition trims the applicationPath from stack traces by default. If stack traces appear broken, verify the path:

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

3. AI Solution Quirks:

   • OpenAI solutions are not always accurate. Test in development before relying on them.
   • Cache AI responses to avoid rate limits:

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

4. Flare Configuration:

   • Ensure spatie/flare-client-php is installed for Flare features:

     composer require spatie/flare-client-php
     

   • Anonymize IPs in production to comply with privacy laws:

     $flare->anonymizeIp();
     

5. Middleware Conflicts:

   • If Ignition doesn’t trigger, check for middleware (e.g., App\Exceptions\Handler) that might be swallowing exceptions. Ignition should be registered before other exception handlers.

Debugging Tips

1. Disable Ignition Temporarily: Comment out Ignition::make()->register() to test if another package is interfering with error handling.

2. Check for Overrides: If custom solutions aren’t showing, verify:

   • The exception implements ProvidesSolution.
   • The solution provider is correctly registered.
   • No other middleware is modifying the exception.

3. Flare Not Receiving Errors:

   • Validate the API key in config/services.php.
   • Ensure runningInProductionEnvironment(true) is set.
   • Check network requests in browser dev tools for Flare API calls.

4. Performance Impact:

   • AI solutions and Flare integration add overhead. Disable in non-critical paths:

     if (app()->environment('local')) {
         Ignition::make()->addSolutionProviders([$aiProvider])->register();
     }
     

Extension Points

1. Custom Error Pages: Override Ignition’s UI by publishing and modifying its assets:

   composer require spatie/ignition-ui
   php artisan vendor:publish --provider="Spatie\Ignition\IgnitionServiceProvider" --tag="ignition-assets"
   

2. Solution Providers: Create reusable providers for team-wide error patterns:

   class DatabaseSolutionProvider implements \Spatie\Ignition\Contracts\HasSolutionsForThrowable {
       public function canSolve(\Throwable $throwable): bool {
           return str_contains($throwable->getMessage(), 'SQLSTATE[42S02]');
       }
       public function getSolutions(\Throwable $throwable): array {
           return [new \Spatie\Ignition\Contracts\Solution {
               // Solution logic...
           }];
       }
   }
   

3. Flare Middleware: Extend Flare reports with custom logic (e.g., user sessions, logs):

   class SessionMiddleware implements \Spatie\FlareClient\FlareMiddleware\FlareMiddleware {
       public function handle(\Spatie\FlareClient\Report $report, \Closure $next) {
           $report->context('Session', session()->all());
           return $next($report);
       }
   }
   

4. Dark Mode Customization: Override CSS variables in the published assets to match your app’s theme:

   :root {
       --ignition-bg: #1a1a1a;
       --ignition-text: #e0e0e0;
   }