Honeybadger Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require chesscom/honeybadger-bundle
   

   Ensure Chesscom\HoneybadgerBundle\ChesscomHoneybadgerBundle is registered in config/bundles.php under the Chesscom\HoneybadgerBundle namespace.

2. Configure Honeybadger Add your Honeybadger API key to .env:

   HONEYBADGER_API_KEY=your_api_key_here
   

   Publish the default config (if needed):

   php bin/console config:dump-reference Chesscom\HoneybadgerBundle\Resources\config\services.yaml
   

   Override defaults in config/packages/chesscom_honeybadger.yaml:

   chesscom_honeybadger:
       api_key: '%env(HONEYBADGER_API_KEY)%'
       environment: '%kernel.environment%'
       ignore_status_codes: [404, 500]  # Optional
   

3. First Use Case: Logging Errors The bundle auto-captures exceptions thrown in controllers/services. Test by forcing an error in a controller:

   public function testError(Symfony\Component\HttpFoundation\Response $response)
   {
       throw new \RuntimeException('Test error for Honeybadger');
   }
   

   Verify the error appears in your Honeybadger dashboard.

Implementation Patterns

Core Workflows

1. Exception Handling

   • Auto-Capture: The bundle hooks into Symfony’s kernel.exception event, forwarding uncaught exceptions to Honeybadger.
   • Manual Notifications: Use the Honeybadger service to notify Honeybadger explicitly:

     use Chesscom\HoneybadgerBundle\Honeybadger;
     
     public function __construct(private Honeybadger $honeybadger) {}
     
     public function riskyOperation()
     {
         try {
             // Risky code...
         } catch (\Exception $e) {
             $this->honeybadger->notify($e, context: ['user_id' => 123]);
         }
     }
     

2. Contextual Data Attach metadata to errors for debugging:

   $this->honeybadger->notify($e, [
       'user' => $user->toArray(),
       'request' => $request->query->all(),
   ]);
   

3. Ignoring Errors Exclude specific exceptions or status codes in config:

   chesscom_honeybadger:
       ignore_exceptions: ['Symfony\Component\HttpKernel\Exception\NotFoundHttpException']
       ignore_status_codes: [404]
   

4. Custom Error Groups Tag errors for organization in Honeybadger:

   $this->honeybadger->notify($e, group: 'payment-failures');
   

Integration Tips

• Symfony Monolog Bridge: If using Monolog, configure the bundle to forward log errors:

  chesscom_honeybadger:
      log_errors: true  # Requires Monolog bundle
  

• Async Notifications: For performance, use Honeybadger’s async API (requires manual implementation via Honeybadger::notifyAsync() if the bundle doesn’t support it natively).
• Environment-Specific Config: Leverage %kernel.environment% to disable Honeybadger in dev:

  chesscom_honeybadger:
      enabled: '%kernel.debug% ? false : true%'
  

Gotchas and Tips

Pitfalls

1. API Key Exposure

   • Never commit .env to version control. Use env() in config or a secure secrets manager.
   • Validate the API key is set in config/packages/chesscom_honeybadger.yaml:

     api_key: '%env(HONEYBADGER_API_KEY)%'
     

2. Duplicate Errors

   • Honeybadger deduplicates errors by default, but custom contexts (e.g., user_id) may create duplicates. Use a stable identifier like request_id:

     $this->honeybadger->notify($e, context: ['request_id' => $request->get('X-Request-ID')]);
     

3. Performance Overhead

   • Network calls to Honeybadger’s API add latency. For high-traffic apps, batch notifications or use async queues (e.g., Symfony Messenger).

4. Missing Context in Auto-Captured Errors

   • Auto-captured exceptions lack request/context data. Manually notify critical errors:

     $this->honeybadger->notify($e, context: ['url' => $request->getUri()]);
     

Debugging

• Verify Config:

  php bin/console debug:config chesscom_honeybadger
  

• Check API Calls: Enable Honeybadger’s debug mode in config:

  chesscom_honeybadger:
      debug: true
  

  Logs will appear in var/log/dev.log.

• Test Locally: Use Honeybadger’s sandbox API key to test without real notifications.

Extension Points

1. Custom Error Formatter Override the default error formatter by binding a service:

   services:
       Chesscom\HoneybadgerBundle\ErrorFormatterInterface: '@app.custom_error_formatter'
   

   Implement ErrorFormatterInterface to modify payloads.

2. Pre-Notification Hooks Subscribe to the honeybadger.notify event to modify notifications:

   // config/services.yaml
   services:
       App\EventListener\HoneybadgerListener:
           tags:
               - { name: kernel.event_listener, event: honeybadger.notify, method: onNotify }
   

3. Custom Transport Extend the bundle to support alternative transports (e.g., RabbitMQ) by implementing Honeybadger\TransportInterface.

Pro Tips

• Error Grouping: Use consistent group names (e.g., auth-failures) to organize errors in Honeybadger’s dashboard.
• Severity Levels: Leverage Honeybadger’s severity levels (error, warning, info) for prioritization:

  $this->honeybadger->notify($e, severity: 'warning');
  

• Rate Limiting: Honeybadger’s API has rate limits. Monitor usage in the dashboard to avoid throttling.