Honeybadger Php Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require chesscom/honeybadger-php
   

2. Basic Configuration Add your API key to .env:

   HONEYBADGER_API_KEY=your_api_key_here
   HONEYBADGER_ENVIRONMENT=production
   

3. First Integration Register the middleware in app/Http/Kernel.php:

   protected $middleware = [
       \HoneyBadger\HoneyBadgerMiddleware::class,
   ];
   

4. Verify Setup Trigger a test error (e.g., abort(500) in a route) and check HoneyBadger’s dashboard for the notification.

Implementation Patterns

Laravel-Specific Patterns

1. Exception Handling Override Laravel’s report() method in App\Exceptions\Handler.php:

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

2. Queue-Based Reporting Use Laravel queues to avoid blocking HTTP responses:

   // In a service or controller
   HoneyBadger::notify($exception)->queue();
   

3. Contextual Error Tracking Attach request/user data before notifying:

   HoneyBadger::notify($exception)
       ->context(['user_id' => auth()->id(), 'request_data' => request()->all()]);
   

4. Artisan Command Errors Wrap command logic in a try-catch and notify HoneyBadger:

   try {
       // Command logic
   } catch (\Exception $e) {
       HoneyBadger::notify($e);
       throw $e;
   }
   

5. Middleware for API Errors Create a custom middleware to catch HTTP errors:

   public function handle($request, Closure $next)
   {
       try {
           return $next($request);
       } catch (\Symfony\Component\HttpKernel\Exception\HttpException $e) {
           HoneyBadger::notify($e);
           throw $e;
       }
   }
   

Integration Tips

• Laravel Queues: Use database or redis queues for async error reporting.
• Horizon Integration: Extend the package to support Horizon job failures by listening to failed events.
• Testing: Use HoneyBadgerTestCase for unit/feature tests:

  public function testErrorNotification()
  {
      HoneyBadger::notify(new \Exception('Test'));
      $this->assertHoneyBadgerNotificationSent();
  }
  

• Environment Awareness: Configure different API keys/environments per stage:

  HONEYBADGER_API_KEY_STAGING=...
  HONEYBADGER_API_KEY_PROD=...
  

Gotchas and Tips

Pitfalls

1. API Key Exposure

   • Never commit .env to version control. Use Laravel’s env() helper or config files for sensitive data.
   • Fix: Use config/honeybadger.php with encrypted values if needed.

2. Rate Limiting

   • HoneyBadger’s API may throttle requests during error spikes.
   • Fix: Implement queue-based reporting with exponential backoff:

     HoneyBadger::notify($e)->queue('honeybadger', ['attempts' => 3]);
     

3. Missing Context

   • Errors without context (e.g., user ID, request data) are harder to debug.
   • Fix: Always attach relevant context:

     HoneyBadger::notify($e)->context(['user' => auth()->user()]);
     

4. Performance Overhead

   • Synchronous API calls can slow down responses.
   • Fix: Use queues or defer reporting:

     HoneyBadger::notify($e)->defer();
     

5. Laravel Version Mismatch

   • The package may not support newer Laravel versions (e.g., 10.x).
   • Fix: Check composer.json constraints or fork the package.

Debugging Tips

• Check API Responses Enable debug mode in config/honeybadger.php:

  'debug' => env('HONEYBADGER_DEBUG', false),
  

  This logs API errors to Laravel’s log channel.

• Mock HoneyBadger in Tests Use the HoneyBadgerTestCase trait to verify notifications:

  public function testErrorIsReported()
  {
      HoneyBadger::notify(new \Exception('Test'));
      $this->assertHoneyBadgerNotificationSent();
  }
  

• Inspect Payloads Log the payload before sending:

  HoneyBadger::setLogger(function ($payload) {
      \Log::debug('HoneyBadger payload', ['payload' => $payload]);
  });
  

Extension Points

1. Custom Error Groups Override the group method in a service provider:

   HoneyBadger::extend(function ($notifier) {
       $notifier->group = function ($exception) {
           return 'CustomGroup:' . $exception->getCode();
       };
   });
   

2. Filtering Errors Ignore specific exceptions (e.g., ValidationException):

   HoneyBadger::ignore(function ($exception) {
       return $exception instanceof \Illuminate\Validation\ValidationException;
   });
   

3. Custom Notifiers Add a notifier for third-party services (e.g., Stripe):

   HoneyBadger::notify(new \Stripe\Exception\CardException('Test'))
       ->context(['service' => 'stripe']);
   

4. Webhook Integration Use HoneyBadger’s webhooks to trigger internal alerts (e.g., Slack):

   // In a service provider
   HoneyBadger::webhook('https://your-app.com/honeybadger-webhook');
   

Configuration Quirks

• Environment Variables Prefix HoneyBadger config with HONEYBADGER_ in .env:

  HONEYBADGER_API_KEY=...
  HONEYBADGER_ENVIRONMENT=staging
  HONEYBADGER_DEBUG=true
  

• Fallback Behavior Configure a fallback logger if HoneyBadger fails:

  HoneyBadger::setFallbackLogger(function ($exception) {
      \Log::error('HoneyBadger failed', ['exception' => $exception]);
  });
  

• Payload Size Limits HoneyBadger may reject large payloads. Trim context data:

  HoneyBadger::notify($e)
      ->context(array_slice($context, 0, 10)); // Limit to 10 keys