Getting Started

Minimal Setup

Installation:

composer require spatie/laravel-flare

Publish the config file:

php artisan vendor:publish --provider="Spatie\Flare\FlareServiceProvider" --tag="config"

Configuration: Add your Flare API key to .env:
```
FLARE_API_KEY=your_api_key_here
```
Ensure APP_ENV is set to production (Flare only works in production).
First Use Case: Trigger an error in production (e.g., 1/0 in a route or controller). Flare will automatically capture and display the error in your Flare dashboard.

Implementation Patterns

Core Workflow

Error Reporting:
- Flare integrates seamlessly with Laravel’s exception handler. No manual report() calls needed.
- Example: Throw an exception in a controller:
```
public function riskyOperation()
{
    throw new \Exception("Oops! Something went wrong.");
}
```

Logging:

Add the flare channel to config/logging.php:

'channels' => [
    'flare' => [
        'driver' => 'flare',
        'minimal_log_level' => env('FLARE_LOG_LEVEL', 'debug'),
    ],
],

Log messages will appear in Flare with context (e.g., route, user, request data).

Example:

\Log::debug('User logged in', ['user_id' => auth()->id()]);

Performance Monitoring:

Sampling: Use DynamicSampler to filter traces (e.g., sample 100% of /admin/* routes):

'sampler' => \Spatie\Flare\Samplers\DynamicSampler::class,
'sampler_rules' => [
    ['route_name' => '/admin/*', 'percentage' => 100],
],

Daemon Mode: For local development, use the DaemonSender:

'sender' => \Spatie\Flare\Senders\DaemonSender::class,

Custom Data Collection:

Extend Flare’s context with custom attributes:

use Spatie\Flare\Flare;

Flare::collect(function () {
    return [
        'custom_metric' => 'value',
        'user_segment' => auth()->user()->segment,
    ];
});

Queue Jobs:
- Flare automatically captures queue job failures. Ensure your queue worker runs with:
```
php artisan queue:work --daemon
```

Integration Tips

Livewire: Flare supports Livewire v4 traces out of the box. No additional setup required.

API Routes: Use route_name in sampler rules to monitor specific API endpoints:

'sampler_rules' => [
    ['route_name' => 'api.v1.users.store', 'percentage' => 100],
],

Censoring Sensitive Data: Automatically censor cookies/session data in config/flare.php:
```
'censor' => [
    'cookies' => true,
    'session' => true,
],
```
Testing: Use the flare:test command to simulate errors in staging:
```
php artisan flare:test --message="Test error" --level=error
```

Gotchas and Tips

Pitfalls

Environment Mismatch:
- Flare only works in production (APP_ENV=production). Errors in local or testing will not be sent.
- Fix: Set APP_ENV=production in .env for testing Flare.
API Key Validation:
- If FLARE_API_KEY is missing or invalid, Flare silently disables itself. Verify the key in the Flare dashboard.
Queue Job Sampling:
- Jobs processed via queue:work --sync are not sampled by default. Use DaemonSender for local testing:
```
'sender' => \Spatie\Flare\Senders\DaemonSender::class,
```
Log Level Filtering:
- Logs below minimal_log_level (default: debug) are dropped before sending. Adjust in config/flare.php:
```
'minimal_log_level' => 'info', // Only send 'info', 'notice', 'error', etc.
```
Livewire Component Traces:
- For Livewire v3, ensure app_debug is true in config/app.php to capture component traces.

Database Query Binding Quirks:

Query exceptions now quote string bindings to avoid SQL injection warnings in Flare. Example:

-- Before: `SELECT * FROM users WHERE email = user@example.com`
-- After: `SELECT * FROM users WHERE email = 'user@example.com'`

Debugging Tips

Check Flare Context: Inspect the flare_context table in your database (if using the daemon) to debug missing data:
```
php artisan flare:context
```
Disable Flare Temporarily: Set FLARE_DISABLED=true in .env to bypass Flare without removing the package.

Sampler Debugging: Log sampler rules to verify they’re applied:

\Log::debug('Flare sampler rules:', ['rules' => config('flare.sampler_rules')]);

Daemon Issues:
- Ensure the Flare daemon is running:
```
php artisan flare:daemon
```
- Check daemon logs for errors:
```
tail -f storage/logs/flare-daemon.log
```

Extension Points

Custom Collectors: Create a custom collector to add application-specific data:

use Spatie\Flare\Flare;

Flare::collect(function () {
    return [
        'app_version' => config('app.version'),
        'feature_flags' => config('feature.flags'),
    ];
});

Override Default Senders: Replace the default LaravelHttpSender with a custom sender (e.g., for rate-limiting):
```
'sender' => \App\Services\CustomFlareSender::class,
```

Attribute Providers: Extend request/console attribute providers for custom metadata:

use Spatie\Flare\Flare;

Flare::extendRequestAttributes(function ($request) {
    return ['custom_header' => $request->header('X-Custom-Header')];
});

Log Channel Customization: Modify the flare channel in config/logging.php to include/exclude handlers:

'flare' => [
    'driver' => 'flare',
    'minimal_log_level' => 'debug',
    'handler' => \Monolog\Handler\StreamHandler::class, // Optional: Route logs to a file first
],

Sampler Rules: Dynamically set sampler rules based on environment:

'sampler_rules' => env('FLARE_SAMPLER_RULES', json_encode([
    ['route_name' => 'api/*', 'percentage' => 10],
])),

Pro Tips

Group Errors by Custom Tags: Use Flare::group() to categorize errors in the dashboard:

Flare::group('payment_processing')->collect(function () {
    // Your code that might throw an exception
});

Monitor Queue Lag: Sample queue jobs with high latency:

'sampler_rules' => [
    ['queue_name' => 'high-priority', 'percentage' => 100],
],

Exclude Routes from Traces: Use negative sampling to exclude routes (e.g., health checks):
```
'sampler_rules' => [
    ['route_name' => 'health-check', 'percentage' => 0],
],
```

Local Development with Daemon: Run the daemon locally to test Flare without hitting the API:

php artisan flare:daemon --port=4077

Configure the daemon in config/flare.php:

'sender' => \Spatie\Flare\Senders\DaemonSender::class,
'daemon_url' => 'http://localhost:4077',

Laravel Flare Laravel Package