Getting Started

Minimal Setup

Installation:
```
composer require spatie/laravel-ignition
```
Ignition auto-registers via Laravel's service provider system—no manual configuration is required for basic usage.
First Use Case: Trigger an error in your application (e.g., 1/0 in a route or controller). Ignition replaces Laravel’s default error page with an interactive, detailed error screen featuring:
- Stack traces with collapsible sections.
- Context data (request, session, variables).
- Quick solutions (e.g., "Missing use statement?").
- Copy-to-clipboard functionality for error details.
Where to Look First:
- Error Page: The UI itself (e.g., http://your-app.test/ignition for local testing).
- Configuration: config/ignition.php (customize solutions, AI keys, or Flare integration).
- Documentation: Flare’s Ignition Docs for advanced features.

Implementation Patterns

Daily Workflows

Local Development:
- Debugging: Ignition’s stack traces and context panels replace dd() or var_dump() for complex debugging. Use the "Copy Exception" button to share errors with teammates.
- Quick Fixes: Click "Suggested Solutions" for common issues (e.g., missing use statements, route definitions).
- Environment Context: Toggle the "Show Environment" button to inspect .env variables (redacted by default).
Production Monitoring (Flare Integration):
- Add your Flare API key to .env:
```
FLARE_API_KEY=your_key_here
```
- Errors auto-sync to Flare’s dashboard, including:
  - Request/response data.
  - Database queries (if using Flare’s query logging).
  - Performance metrics.
- Trigger a Test Error: Use php artisan flare:test-error to verify setup.

Customizing Solutions:

Extend Ignition’s "Suggested Solutions" with your team’s patterns:

// app/Providers/IgnitionServiceProvider.php
use Spatie\Ignition\Solutions\Solution;

public function register()
{
    Solution::extend('custom_solution', function () {
        return Solution::create('Custom Solution')
            ->setDescription('Add this to your config file:')
            ->setSolution('<code>...</code>');
    });
}

Artisan Commands:
- Clear Ignition Cache:
```
php artisan ignition:clear
```
- Share Errors Publicly (Flare):
```
php artisan flare:share
```

Testing:

Mock Ignition in PHPUnit:

use Spatie\Ignition\Ignition;

public function testErrorPage()
{
    Ignition::fake(); // Disable Ignition for the test
    // ... test code ...
}

Integration Tips

With Livewire:
- Ignition automatically captures Livewire component errors with stack traces pointing to .blade.php files.
With Queues:
- Failed jobs show detailed payloads (decoded if serialized). Use the "Replay Job" button to debug queue workers.
With API Testing:
- Ignition’s error pages work for API routes. Use the "Response" tab to inspect raw HTTP responses.
With Homestead/Sail:
- Ignition’s "Sail Helper" detects missing sail commands and suggests fixes (e.g., sail artisan migrate).
With IDEs:
- Click the "Open in IDE" button to jump to the error’s file/line in PhpStorm, VSCode, or other editors.

Gotchas and Tips

Pitfalls

Flare API Key Leaks:
- Risk: Accidentally committing FLARE_API_KEY to version control.
- Fix: Add .env to .gitignore and use Laravel’s .env.example for templates.
Sensitive Data Exposure:
- Risk: Context panels may expose passwords or tokens in logs/errors.
- Fix: Configure ignition.php to redact sensitive keys:
```
'redact' => [
    'password',
    'api_token',
    'secret_*',
],
```
Performance Impact:
- Risk: Ignition collects context data, which may slow down error pages in high-traffic apps.
- Fix: Disable in production (Ignition is designed for development/staging):
```
'enabled' => env('APP_ENV') !== 'production',
```
Middleware Conflicts:
- Risk: Some middlewares (e.g., CORS) may interfere with Ignition’s error handling.
- Fix: Ensure Ignition’s middleware runs after your app’s middleware in app/Http/Kernel.php:
```
protected $middleware = [
    // ...
    \Spatie\Ignition\Middleware\Ignition::class,
];
```
Livewire 4+ Support:
- Gotcha: Ignition v2.10+ drops Laravel 10/Livewire 2 support. Update if using newer versions:
```
composer require laravel/livewire:"^4.0"
```

Debugging Tips

Disable Ignition Temporarily:
- Set IGNITION_ENABLED=false in .env to bypass Ignition for testing.
Log Leakage:
- If HTML view data leaks into laravel.log, ensure you’re using Ignition v1.7.1+ (fixed in #224).

Custom Exception Handling:

To exclude certain exceptions from Ignition:

Ignition::ignore(function (Throwable $e) {
    return $e instanceof CustomException;
});

Symfony 8/Laravel 13:
- Ignition v2.12+ supports Symfony 8. If upgrading, check for deprecation warnings (e.g., Request::get()).
AI Solutions:
- Requires an OpenAI API key (OPENAI_API_KEY in .env). Disable with:
```
'ai' => [
    'enabled' => false,
],
```

Extension Points

Custom Context:

Add application-specific context to errors:

use Spatie\Ignition\Context\Context;

Context::capture(function () {
    return [
        'user_id' => auth()->id(),
        'custom_metric' => app()->get('custom.metric'),
    ];
});

Override Views:
- Publish and modify Ignition’s Blade templates:
```
php artisan vendor:publish --tag=ignition-views
```
- Edit files in resources/views/vendor/ignition/.

Solutions Providers:

Create reusable solution sets for your team:

Solution::extend('laravel-shift', function () {
    return Solution::create('Laravel Shift')
        ->setDescription('Check Laravel Shift for migrations:')
        ->setSolution('https://laravel-shift.com');
});

Flare Middleware:

Extend Flare’s error reporting with custom data:

use Spatie\FlareClient\Flare;

Flare::extend(function ($report) {
    $report->addContext('custom', ['key' => 'value']);
});

Testing Ignition:
- Use Ignition::fake() in tests to simulate errors without triggering the UI:
```
$this->expectException(DivisionByZeroError::class);
Ignition::fake();
1 / 0;
```

Laravel Ignition Laravel Package