Bugsnag Laravel Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require bugsnag/bugsnag-laravel
   

   Publish the config file:

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

2. Configuration:

   • Add your API key to .env:

     BUGSNAG_API_KEY=your_api_key_here
     

   • Update config/bugsnag.php with your project details (e.g., releaseStage, appVersion).

3. First Use Case:

   • Automatic Reporting: Unhandled exceptions (e.g., 500 errors) are automatically reported. Test by triggering an error in a route:

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

   • Manual Reporting: Report handled exceptions explicitly:

     try {
         // Risky operation
     } catch (\Exception $e) {
         Bugsnag::notify($e, [
             'custom_data' => ['user_id' => auth()->id()]
         ]);
     }
     

Implementation Patterns

Core Workflows

1. Automatic Exception Handling:

   • Integrates seamlessly with Laravel’s exception handler (app/Exceptions/Handler.php). No manual setup required for unhandled exceptions.
   • Example override to customize reporting:

     public function report(Throwable $exception)
     {
         if (app()->bound('bugsnag')) {
             Bugsnag::notify($exception);
         }
         parent::report($exception);
     }
     

2. Manual Error Reporting:

   • Use Bugsnag::notify() in services, jobs, or controllers for granular control.
   • Attach context (e.g., user data, request payloads):

     Bugsnag::notify($exception, [
         'user' => auth()->user(),
         'request' => request()->all(),
         'custom_metadata' => ['feature_flag' => 'new_ui']
     ]);
     

3. Middleware for Global Context:

   • Add user/request data to every error report via middleware:

     public function handle($request, Closure $next)
     {
         Bugsnag::leaveBreadcrumb('User Action', [
             'user_id' => auth()->id(),
             'action' => 'view_profile'
         ]);
         return $next($request);
     }
     

4. Lumen Integration:

   • Register the service provider in bootstrap/app.php:

     $app->register(\Bugsnag\BugsnagLaravel\BugsnagServiceProvider::class);
     

   • Use Bugsnag::notify() identically to Laravel.

5. Testing:

   • Mock Bugsnag in unit tests to verify error reporting:

     $this->partialMock(Bugsnag::class, function ($mock) {
         $mock->shouldReceive('notify')->once();
     });
     

Gotchas and Tips

Pitfalls

1. Sensitive Data Leakage:

   • Avoid attaching raw request data (request()->all()) or user passwords to reports. Use Bugsnag::notify() with filtered payloads:

     Bugsnag::notify($e, [
         'user' => auth()->user()->only('id', 'email')
     ]);
     

   • Configure config/bugsnag.php to redact sensitive keys:

     'redact_keys' => ['password', 'api_key', 'credit_card'],
     

2. Duplicate Reports:

   • Bugsnag deduplicates errors by default, but ensure consistent releaseStage and appVersion in config to avoid fragmentation.

3. Performance Overhead:

   • Heavy breadcrumb logging (Bugsnag::leaveBreadcrumb()) can slow down requests. Use sparingly in production.

4. Lumen Quirks:

   • Ensure the service provider is registered before the Illuminate\Foundation\Bootstrap\LoadEnvironmentVariables bootstrap step to avoid missing .env variables.

Debugging

1. Verify Reports:

   • Check the Bugsnag dashboard for incoming errors. Use the releaseStage to filter test vs. production reports.

2. Local Testing:

   • Disable auto-reporting in config/bugsnag.php during development:

     'enabled' => env('APP_ENV') !== 'local',
     

3. Log Levels:

   • Bugsnag respects Laravel’s log levels. For critical errors, use:

     Bugsnag::notify($e, [], Bugsnag::SEVERITY_CRITICAL);
     

Extension Points

1. Custom Error Groups:

   • Group related errors using groupingHash:

     Bugsnag::notify($e, [], null, null, 'unique_grouping_hash');
     

2. Event Listeners:

   • Attach data to errors via Laravel events (e.g., illuminate.auth.Event):

     public function handle(Authenticated $event)
     {
         Bugsnag::leaveBreadcrumb('User Logged In', ['user_id' => $event->user->id]);
     }
     

3. Webhook Integration:

   • Use Bugsnag’s webhooks to trigger Slack/email alerts for critical errors.

4. Custom Error Classes:

   • Extend Bugsnag\BugsnagLaravel\Bugsnag to add project-specific methods:

     class CustomBugsnag extends Bugsnag
     {
         public function reportPaymentFailure($exception, $amount)
         {
             $this->notify($exception, [
                 'payment' => ['amount' => $amount, 'currency' => 'USD']
             ]);
         }
     }