Bugsnag Laravel Package

Getting Started

Minimal Setup for Laravel

1. Install the Package

   composer require bugsnag/bugsnag
   

2. Publish Configuration

   php artisan vendor:publish --provider="Bugsnag\Bugsnag\BugsnagServiceProvider"
   

   This generates a .env.bugsnag file. Add your API key:

   BUGSNAG_API_KEY=your_api_key_here
   

3. Configure Laravel Integration Add to config/bugsnag.php:

   'laravel' => [
       'enabled' => env('BUGSNAG_ENABLED', true),
       'report_queries' => env('BUGSNAG_REPORT_QUERIES', false),
   ],
   

4. First Use Case: Auto-Reporting Exceptions Bugsnag automatically captures uncaught exceptions. Test it by throwing an exception in a route:

   Route::get('/test-error', function() {
       throw new \Exception("Test error for Bugsnag");
   });
   

Implementation Patterns

Core Workflows

1. Automatic Exception Handling Bugsnag integrates with Laravel’s exception handler (App\Exceptions\Handler). Extend it to customize reporting:

   public function report(Throwable $exception)
   {
       if (config('bugsnag.laravel.enabled')) {
           Bugsnag::notifyException($exception);
       }
       parent::report($exception);
   }
   

2. Manual Error Reporting Use Bugsnag::notify() for custom events or handled exceptions:

   try {
       // Risky operation
   } catch (\Exception $e) {
       Bugsnag::notifyException($e, [
           'user' => ['id' => auth()->id(), 'email' => auth()->user()->email],
           'context' => 'Payment processing',
       ]);
   }
   

3. Middleware for User Context Attach user data globally via middleware:

   public function handle($request, Closure $next)
   {
       Bugsnag::configure()->setUser([
           'id' => auth()->id(),
           'email' => auth()->user()->email,
           'name' => auth()->user()->name,
       ]);
       return $next($request);
   }
   

4. Query Monitoring (Laravel-Specific) Enable in config/bugsnag.php and use:

   Bugsnag::notifyQuery('SELECT * FROM users', [
       'duration' => 1500, // ms
       'bindings' => ['user_id' => 123],
   ]);
   

Integration Tips

• Lumen: Use the Bugsnag\Bugsnag\Lumen\BugsnagServiceProvider.
• Symfony/Silex: Configure via Bugsnag\Bugsnag\Symfony\BugsnagBundle.
• Custom Events: Use Bugsnag::notify() with structured data for non-exception events (e.g., API failures).
• Environment-Specific Config: Disable in local environments:

  'enabled' => app()->environment(['staging', 'production']),
  

Gotchas and Tips

Pitfalls

1. Sensitive Data Leakage

   • Risk: Accidentally sending PII (e.g., passwords, tokens) in error payloads.
   • Fix: Use beforeNotify to scrub data:

     Bugsnag::configure()->setBeforeNotify(function ($payload) {
         unset($payload['request']['headers']['authorization']);
         return $payload;
     });
     

2. Duplicate Reports

   • Cause: Multiple notify() calls for the same exception (e.g., in middleware + exception handler).
   • Fix: Use Bugsnag::notifyOnce() or guard with a flag:

     if (!session()->has('bugsnag_reported')) {
         Bugsnag::notify($exception);
         session()->put('bugsnag_reported', true);
     }
     

3. Performance Overhead

   • Issue: Network calls to Bugsnag during critical paths (e.g., API requests).
   • Fix: Disable for non-critical errors or use async reporting:

     Bugsnag::notifyAsync($exception); // Non-blocking
     

4. Laravel Queue Conflicts

   • Problem: Bugsnag’s queue driver may conflict with Laravel’s job queues.
   • Fix: Explicitly set the queue connection:

     Bugsnag::configure()->setQueueConnection('database');
     

Debugging Tips

• Payload Inspection: Use Bugsnag::notify() with debug: true to log payloads locally:

  Bugsnag::notify($exception, [], ['debug' => true]);
  

• Environment Variables: Validate .env.bugsnag is loaded (check config('bugsnag.api_key')).
• Rate Limits: Monitor 503 responses; adjust sendRate in config if needed:

  'sendRate' => 1.0, // 1 error per second
  

Extension Points

1. Custom Error Classes Override Bugsnag\Bugsnag\ExceptionHandler to handle domain-specific exceptions:

   Bugsnag::configure()->setExceptionHandler(function ($exception) {
       if ($exception instanceof \App\Exceptions\PaymentFailed) {
           return new \Bugsnag\Bugsnag\Error($exception, [
               'type' => 'payment_failure',
               'amount' => $exception->amount,
           ]);
       }
       return null; // Let Bugsnag handle it
   });
   

2. Breadcrumbs Add contextual events before errors:

   Bugsnag::leaveBreadcrumb('User clicked', ['button' => 'submit']);
   

3. Release Tracking Use Bugsnag::configure()->setReleaseStage() to track deployments:

   Bugsnag::configure()->setReleaseStage('production');
   

4. Ignoring Errors Filter out known false positives (e.g., deprecation notices):

   Bugsnag::configure()->setIgnoreClasses([
       \DeprecatedFunctionalityException::class,
   ]);