Symfony Ignition Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require spatie/symfony-ignition-bundle
   

   Add the bundle to config/bundles.php:

   return [
       // ...
       Spatie\SymfonyIgnition\SymfonyIgnitionBundle::class => ['all' => true],
   ];
   

2. First Use Case: Trigger an error (e.g., throw new \Exception('Test error');) and visit the page in your browser. Ignition will replace Symfony’s default error page with a rich, interactive UI.

3. Key Files:

   • config/packages/spatie_symfony_ignition.yaml (default config).
   • public/ignition (static assets; avoid modifying unless extending).

Implementation Patterns

Core Workflows

1. Debugging Exceptions:

   • Ignition captures exceptions, displays stack traces, and highlights problematic lines in your code.
   • Example: Click the file path in the stack trace to open the editor (if using Laravel IDE Helper or similar).

2. Environment-Specific Behavior:

   • Disable Ignition in production by setting ignition.enabled: false in .env or config.
   • Use IGNITION_LEVEL=local to restrict visibility to specific environments.

3. Integration with Laravel:

   • Works seamlessly with Laravel’s exception handling (e.g., App\Exceptions\Handler). Ignition will render Laravel’s formatted exceptions.
   • Tip: Pair with spatie/laravel-ignition (if using Laravel) for tighter integration.

4. Custom Error Pages:

   • Override the default Ignition template by publishing assets:

     php bin/console assets:install public
     

   • Modify templates/ignition/error.html.twig (Symfony) or resources/views/vendor/ignition/error.blade.php (Laravel).

5. API Errors:

   • Ignition supports JSON responses. Configure ignition.json_errors: true to render API errors in the UI.

6. Collaboration Features:

   • Share error screenshots or links with teammates via Ignition’s "Share" button.
   • Use the "Copy Code" button to extract exception details for bug reports.

Gotchas and Tips

Pitfalls

1. Performance Overhead:

   • Ignition adds ~100KB to your assets. Disable in production (ignition.enabled: false).
   • Workaround: Use ignition.ignore_routes to exclude specific routes (e.g., API endpoints).

2. Caching Issues:

   • Clear cache after publishing custom templates:

     php bin/console cache:clear
     

   • Ignition assets may be cached by CDNs. Use cache-busting queries (e.g., ?v=1.0) if needed.

3. Symfony-Specific Quirks:

   • Debug Toolbar Conflict: Ignition may interfere with Symfony’s Web Profiler. Disable Profiler if Ignition behaves erratically.
   • Kernel Debug Mode: Ensure debug: true in .env for full Ignition functionality.

4. Laravel-Specific Notes:

   • If using Laravel, prefer spatie/laravel-ignition for Laravel-specific features (e.g., route list integration).
   • Ignition may not show Laravel’s render() method details by default. Use ignition.show_laravel_exceptions: true in config.

5. Dark Mode:

   • Dark mode is auto-detected but may not work perfectly with custom themes. Override CSS variables in your published assets.

Debugging Tips

1. Log Inspection:

   • Check var/log/dev.log for Ignition-related errors (e.g., missing files or config issues).

2. Disable Ignition Temporarily:

   • Set IGNITION_LEVEL=none in .env to revert to Symfony’s default error pages for troubleshooting.

3. Custom Exception Handling:

   • Ignition respects Symfony’s ExceptionListener interface. If exceptions aren’t captured, verify your listener is registered.

4. Asset Loading:

   • If Ignition assets fail to load, verify the public/ignition directory exists and permissions are correct (chmod -R 755 public/ignition).

Extension Points

1. Custom Error Data:

   • Add context to errors using Ignition::share() in your ExceptionListener:

     use Spatie\SymfonyIgnition\Ignition;
     
     public function onKernelException(GetResponseForExceptionEvent $event) {
         Ignition::share('user_id', auth()->id());
     }
     

2. Event Listeners:

   • Extend Ignition’s behavior via events:

     // config/services.yaml
     Spatie\SymfonyIgnition\Event\IgnitionEvents::ERROR_VIEW_CREATED:
         listener: App\Listener\CustomErrorListener
     

3. Theming:

   • Override SCSS variables in public/ignition/scss/_variables.scss for global styling changes.

4. Route Filtering:

   • Exclude routes from Ignition’s error pages:

     # config/packages/spatie_symfony_ignition.yaml
     ignition:
         ignore_routes:
             - ^/api/
             - ^/healthcheck