Laravel Flare Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require spatie/laravel-flare
   

   Publish the config file:

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

2. Configuration:

   • Add your Flare API key to .env:

     FLARE_API_KEY=your_api_key_here
     

   • Ensure FLARE_ENABLED=true in .env (default is false in production).

3. First Use Case:

   • Trigger an error (e.g., 1/0 in Tinker or a route) and verify it appears in your Flare dashboard.
   • Livewire v4 Support: Test with Livewire components (SFCs) to ensure stack traces render correctly.

Implementation Patterns

Core Workflow

1. Error Capture:

   • Flare automatically captures exceptions via Laravel’s App\Exceptions\Handler (report() method).
   • Livewire v4: Stack traces for Livewire components (SFCs) are now properly resolved. No manual changes required.

2. Custom Data Injection:

   • Attach context to errors using Flare::capture() or Flare::captureException():

     try {
         // Risky operation
     } catch (\Exception $e) {
         Flare::captureException($e, [
             'user_id' => auth()->id(),
             'custom_metric' => 'value',
         ]);
     }
     

3. Environment-Specific Behavior:

   • Disable Flare in local or testing environments via flare.php:

     'enabled' => env('FLARE_ENABLED', false),
     'except' => [
         'local',
         'testing',
     ],
     

4. Middleware Integration:

   • Extend HandleFlare middleware to conditionally enable/disable Flare:

     public function handle($request, Closure $next) {
         if ($request->ip() === '123.123.123.123') {
             config(['flare.enabled' => false]);
         }
         return $next($request);
     }
     

5. Queueing Errors:

   • Flare uses Laravel’s queue system. Ensure the queue worker runs:

     php artisan queue:work --daemon
     

6. Testing:

   • Mock Flare in tests by overriding report() in Handler:

     public function report(Throwable $exception) {
         if (app()->environment('testing')) {
             return; // Skip Flare in tests
         }
         parent::report($exception);
     }
     

New: Route Error Grouping

• 4xx Errors: Unmatched route errors (e.g., 404, 405) are now grouped under errors::{status_code} in Flare.
  • Example: A 404 error will appear under errors:404 in the dashboard.
  • Useful for analyzing API/route-specific failures without manual tagging.

Gotchas and Tips

Pitfalls

1. API Key Leaks:

   • Never commit .env to version control. Use environment variables or a secrets manager.
   • Tip: Add .env to .gitignore and run php artisan config:clear after deploying.

2. Queue Delays:

   • If errors don’t appear, verify:
     • Queue worker is running (php artisan queue:work).
     • Database connection (Flare uses queue tables).
     • Debug: Check php artisan queue:failed-table for failed jobs.

3. Sensitive Data Exposure:

   • Exclude sensitive fields in flare.php:

     'ignored_request_data' => [
         'password',
         'credit_card',
     ],
     

4. Livewire v4 Stack Traces:

   • Fix in 2.8.0: Stack traces for Livewire components (SFCs) now render correctly.
   • Tip: Test Livewire components post-upgrade to confirm traces display properly.

5. Performance Impact:

   • Flare adds minimal overhead (~50ms). Ensure queue workers handle load, especially for high-traffic apps.

Debugging

1. Log Level:

   • Enable debug logging for Flare in config/logging.php:

     'channels' => [
         'flare' => [
             'driver' => 'single',
             'path' => storage_path('logs/flare.log'),
             'level' => 'debug',
         ],
     ],
     

   • Check storage/logs/flare.log for transmission issues.

2. Network Issues:

   • Test connectivity to Flare’s API:

     curl -X POST https://flareapp.io/api/v1/errors -H "Authorization: Bearer YOUR_KEY"
     

3. Route Error Grouping:

   • If 4xx errors aren’t grouped as expected, verify:
     • No custom exception handlers override Flare’s default behavior.
     • The flare.php config hasn’t disabled grouping.

Extension Points

1. Custom Error Data:

   • Extend Flare’s payload with app metadata:

     Flare::extend(function ($payload) {
         $payload['app_version'] = config('app.version');
         return $payload;
     });
     

2. Webhook Notifications:

   • Configure Slack/Teams alerts via Flare’s webhook feature (dashboard).
   • Tip: Use environment-specific webhook URLs in flare.php.

3. Ignition Integration:

   • Combine with spatie/laravel-ignition for local dev:

     // In Handler.php
     if (app()->environment('local')) {
         return false; // Skip Flare locally
     }
     

4. Rate Limiting:

   • Throttle Flare requests in AppServiceProvider:

     use Illuminate\Support\Facades\RateLimiter;
     
     RateLimiter::for('flare', function () {
         return Limit::perMinute(100)->by($this->app['request']->ip());
     });
     

5. Livewire-Specific Debugging:

   • For Livewire v4 issues, check:
     • Component file paths in stack traces.
     • Tip: Use Flare::capture() in handleError() methods of Livewire components for granular context.