Ignition Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require spatie/ignition
   

   For Laravel, use spatie/laravel-ignition instead (preferred for Laravel projects).

2. Basic Registration (in bootstrap/app.php or equivalent):

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

3. First Use Case:

   • Trigger an exception (e.g., throw new Exception('Test error');).
   • Visit the route where the exception occurs. Ignition will render a rich, interactive error page with:
     • Stack trace visualization.
     • Copy-to-clipboard buttons for code snippets.
     • Dark/light mode toggle.

Implementation Patterns

Core Workflows

1. Environment-Specific Configuration:

   // Disable in production (default)
   Ignition::make()
       ->shouldDisplayException(app()->environment('local'))
       ->register();
   
   // Force dark mode
   Ignition::make()
       ->setTheme('dark')
       ->register();
   

2. Solution Providers:

   • Built-in Solutions: Ignition auto-detects common issues (e.g., undefined methods, missing routes).
   • Custom Solutions:

     // Register a solution provider
     Ignition::make()
         ->addSolutionProviders([
             \App\Providers\CustomSolutionProvider::class,
         ])
         ->register();
     

3. Flare Integration (for error monitoring):

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

4. AI-Powered Solutions (optional):

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

Integration Tips

• Laravel: Use spatie/laravel-ignition for seamless integration with Laravel’s exception handling.
• Symfony/Drupal: Use the respective bundles (symfony-ignition-bundle or ignition module).
• Non-Framework PHP: Register Ignition before any exceptions are caught (e.g., in index.php or public/index.php).
• Middleware: Ignition works alongside Laravel’s App\Exceptions\Handler. Place its registration before the Handler in bootstrap/app.php.

Gotchas and Tips

Pitfalls

1. Registration Timing:

   • Issue: Ignition won’t catch exceptions if registered after the error occurs (e.g., in a service provider’s boot()).
   • Fix: Register Ignition in bootstrap/app.php before the AppServiceProvider.

2. Production Leaks:

   • Issue: Sensitive data (e.g., database credentials) may appear in stack traces.
   • Fix:
     • Use shouldDisplayException(false) in production.
     • Configure Flare to censor fields:

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

3. AI Solution Latency:

   • Issue: OpenAI API calls add delay to error pages.
   • Fix:
     • Cache responses with useCache().
     • Disable in production:

       $aiProvider->useCache(cache(), 0); // Disable caching (or set TTL=0)
       

4. Dark Mode Conflicts:

   • Issue: Custom CSS may override Ignition’s dark mode.
   • Fix: Use !important sparingly or inspect Ignition’s generated classes (e.g., .ignition-dark).

Debugging

• Disable Ignition Temporarily:

  Ignition::make()->shouldDisplayException(false)->register();
  

  Useful for testing if Ignition is interfering with other error handlers.

• Inspect Raw Data: Ignition stores the exception data in $_ignition_exception. Access it in middleware or Blade:

  dd($_ignition_exception); // Debug the raw exception object
  

• Clear Cached Solutions: If AI solutions seem stale, clear the cache:

  php artisan cache:clear
  

Extension Points

1. Custom Solution Providers:

   • Implement HasSolutionsForThrowable to add domain-specific fixes.
   • Example: Detect and solve "missing migration" errors.

2. Flare Middleware:

   • Modify reports before sending to Flare:

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

3. Override Templates:

   • Ignition uses Vue.js for rendering. Override templates by publishing assets:

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

   • Modify resources/js/ignition/ignition.js or resources/css/ignition/ignition.css.

4. Localization:

   • Translate error messages by publishing language files:

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

   • Extend resources/lang/vendor/ignition/en/messages.php.

Pro Tips

• Pair with Laravel Telescope: Use Ignition for development and Telescope for production monitoring (they integrate seamlessly).

• GitHub Actions: Automate error reporting in CI:

  - name: Report errors to Flare
    run: php artisan flare:report --env=testing
    if: failure()
  

• Performance: Ignition adds ~50KB to your assets. For high-traffic apps, consider:

  Ignition::make()->registerOnlyInLocalEnvironment()->register();