Getting Started

Minimal Setup

Installation:
```
composer require spatie/laravel-ignition
```
Ignition is automatically registered via Laravel's service provider discovery.
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 collapsible sections.
- Solutions for common errors (e.g., missing imports, undefined variables).
- Copy-to-clipboard functionality for stack traces.
- Context tabs (Request, Response, Environment, etc.).
Where to Look First:
- Error Page: Inspect the rendered error page for solutions and context.
- Configuration: Publish the config file:
```
php artisan vendor:publish --provider="Spatie\Ignition\IgnitionServiceProvider" --tag="ignition-config"
```
  Edit config/ignition.php to customize behavior (e.g., disable solutions, adjust logging).
- Flare Integration: Configure flare.php for error tracking in production (see Flare docs).

Implementation Patterns

Daily Workflows

Local Development:
- Debugging: Ignition’s interactive UI speeds up debugging by highlighting:
  - Missing imports (e.g., use App\Models\User; not found).
  - Undefined variables/methods with suggested fixes.
  - Database query errors with SQL context.
- Copy-Paste: Use the "Copy" button to share stack traces with teammates.
- Context Tabs: Switch between Request, Response, Environment, and Logs to diagnose issues holistically.
Error Handling:
- Custom Exceptions: Extend Ignition’s solutions for your app-specific errors. Override the Spatie\Ignition\Solutions\Solution class or register custom solutions in ignition.php:
```
'solutions' => [
    \App\Solutions\MyCustomSolution::class,
],
```
- Middleware Integration: Ignition automatically captures exceptions thrown in middleware. For custom middleware, ensure it doesn’t swallow exceptions:
```
public function handle($request, Closure $next) {
    try {
        return $next($request);
    } catch (\Throwable $e) {
        // Let Ignition handle it
        throw $e;
    }
}
```
Production Monitoring:
- Flare Integration: Configure flare.php with your API key to track errors in production:
```
'key' => env('FLARE_API_KEY'),
'project_id' => env('FLARE_PROJECT_ID'),
```
- Error Notifications: Use Flare’s webhooks to notify Slack/email on critical errors.
- Ignored Exceptions: Exclude non-critical errors (e.g., 404s) in ignition.php:
```
'ignore_exceptions' => [
    \Symfony\Component\HttpKernel\Exception\NotFoundHttpException::class,
],
```

Testing:

Assertions: Use Ignition’s assert helpers in tests to verify error pages:

$response = $this->get('/error-route');
$response->assertSee('Ignition Error Page');

Mocking: Disable Ignition in tests via config or middleware:

$this->app->singleton(Ignition::class, function () {
    return Ignition::fake();
});

Performance:
- Exclude Routes: Disable Ignition for API routes or performance-critical paths:
```
Route::middleware(['ignition:off'])->group(function () {
    // Ignition disabled here
});
```
- Queue Reports: For high-traffic apps, queue Flare reports to avoid blocking:
```
'queue_reports' => env('QUEUE_REPORTS', false),
```

Integration Tips

Livewire/Alpine:
- Ignition supports Livewire 3/4 and Alpine.js errors. The error page will show component-specific context (e.g., props, slots).
Octane:
- Works seamlessly with Laravel Octane. Ensure QUEUE_REPORTS is enabled to avoid blocking Swoole workers.
Custom Views:
- Override Ignition’s Blade views by publishing assets:
```
php artisan vendor:publish --provider="Spatie\Ignition\IgnitionServiceProvider" --tag="ignition-views"
```
- Extend resources/views/vendor/ignition/ to modify the error page layout.
Logging:
- Ignition logs errors to laravel.log by default. Customize log channels in ignition.php:
```
'log' => 'single',
'log_level' => 'debug',
```
Security:
- Sensitive Data: Ignition automatically redacts sensitive data (e.g., passwords, API keys) in context tabs. Add custom headers to redact:
```
'ignored_headers' => [
    'x-api-key',
    'authorization',
],
```
- Production: Disable solutions in production to avoid leaking sensitive info:
```
'show_solutions' => env('APP_ENV') !== 'production',
```

Gotchas and Tips

Pitfalls

Double Logging:
- Issue: View data (e.g., Blade templates) may leak into laravel.log due to HTML dumping in context().
- Fix: Updated in v1.7.1/v2.12.0. Ensure you’re on the latest version. If not, manually move HTML dumping to the Flare middleware.
Middleware Order:
- Issue: Some middleware (e.g., TrimStrings, ConvertEmptyStringsToNull) may not execute if placed after Ignition’s middleware.
- Fix: Place Ignition’s middleware (Spatie\Ignition\Middleware\Ignition) last in your $middleware stack:
```
protected $middleware = [
    // Other middleware...
    \Spatie\Ignition\Middleware\Ignition::class,
];
```
Flare Reporting:
- Issue: Reports from queues (e.g., jobs) may not send immediately.
- Fix: Use queue_reports: true in ignition.php or manually trigger:
```
\Spatie\Ignition\Facades\Ignition::report($exception);
```
Livewire/Octane Conflicts:
- Issue: Livewire 3/4 or Octane may interfere with Ignition’s error handling.
- Fix: Ensure compatibility by updating Ignition (v2.6.0+ for Livewire 3, v2.5.2+ for Octane).

Custom Exception Handling:

Issue: Custom exception handlers may override Ignition’s behavior.

Fix: Extend Laravel’s exception handler instead of replacing it:

public function render($request, \Throwable $exception) {
    if (app()->bound('ignition') && $exception instanceof \Throwable) {
        return app('ignition')->render($request, $exception);
    }
    return parent::render($request, $exception);
}

Debugging Tips

Disable Ignition:

Temporarily disable Ignition in AppServiceProvider:

public function boot() {
    if (app()->environment('local')) {
        \Spatie\Ignition\Ignition::fake();
    }
}

Inspect Context:

Use php artisan tinker to inspect Ignition’s context:

$context = \Spatie\Ignition\Facades\Ignition::context();
dd($context->all());

Clear Cache:
- If Ignition behaves unexpectedly, clear Laravel’s cache:
```
php artisan cache:clear
php artisan view:clear
```
Check for Conflicts:
- Disable other error handlers (e.g., Whoops, Debugbar) to isolate issues.

Extension Points

Custom Solutions:

Create a solution for your app’s common errors:

namespace App\Solutions;

use Spatie\Ignition\Solutions\Solution;

class UndefinedModelSolution extends Solution
{
    public function solve($exception)
    {
        return 'Did you forget to define the `App\Models\'.classBasename($exception->model).'` model?';
    }

    public function matches($exception)
    {
        return $exception instanceof \ErrorException
            && str_contains($exception->getMessage(), 'Undefined class');
    }
}

'solutions' => [
    \App\Solutions\UndefinedModelSolution::class,
],

Custom Context:
- Add app-specific context to errors:

Laravel Ignition Laravel Package