Airbrake Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require dbstudios/airbrake-bundle
   

   Add to AppKernel.php:

   new DaybreakStudios\Bundle\AirbrakeBundle\DaybreakStudiosAirbrakeBundle(),
   

2. Configuration: Add to config/parameters.yml:

   parameters:
       airbrake.api_key: 'YOUR_API_KEY'
       airbrake.project_id: YOUR_PROJECT_ID
   

   Enable in config/config.yml:

   daybreak_studios_airbrake:
       enabled: false  # Set to `true` in `config_prod.yml`
       api_key: %airbrake.api_key%
       project_id: %airbrake.project_id%
   

3. First Use Case: Deploy to production (APP_ENV=prod). Exceptions will now auto-report to Airbrake.

Implementation Patterns

Core Workflow

1. Exception Handling:

   • The bundle automatically catches uncaught exceptions in production and sends them to Airbrake.
   • No manual try/catch or throw changes required.

2. Contextual Data:

   • Add custom context via the Airbrake service:

     $this->get('daybreak_studios_airbrake.service.airbrake')->addContext('user_id', $user->id);
     

   • Supports environment and appVersion (set via config or code).

3. Ignored Exceptions:

   • Whitelist exceptions to exclude from Airbrake:

     daybreak_studios_airbrake:
         ignored_exceptions:
             - Symfony\Component\HttpKernel\Exception\HttpExceptionInterface
     

4. Monolog Integration (Optional):

   • Forward log entries (e.g., WARNING+) to Airbrake:

     # services.yml
     airbrake_log_watcher:
         class: DaybreakStudios\Bundle\AirbrakeBundle\Logging\AirbrakeHandler
         arguments: ['@daybreak_studios_airbrake.service.airbrake', 'Monolog\Logger::WARNING']
     

   • Add to Monolog handlers in config.yml:

     monolog:
         handlers:
             airbrake:
                 type: service
                 id: airbrake_log_watcher
     

5. Dynamic Configuration:

   • Override settings per environment (e.g., config_prod.yml):

     daybreak_studios_airbrake:
         enabled: true
         environment: production
         appVersion: 1.0.0
     

Gotchas and Tips

Pitfalls

1. API Key Exposure:

   • Avoid hardcoding %airbrake.api_key% in config.yml (use parameters.yml).
   • Fix: Use .env or parameters.yml for sensitive data.

2. Monolog Handler Conflicts:

   • If Monolog handlers are misconfigured, logs may not forward to Airbrake.
   • Debug: Check monolog.logger service in Symfony’s profiler or logs.

3. Ignored Exceptions:

   • Overly broad ignores (e.g., \Exception) may hide critical errors.
   • Tip: Use FQCNs (e.g., App\Exception\PaymentFailedException).

4. Deprecated Symfony Support:

   • Last release (2016) supports Symfony 2.3–3.x. For newer versions, fork or use alternatives like sentry/sentry-symfony.

5. Network Issues:

   • Airbrake API failures may silently drop errors. Add a fallback logger:

     $airbrake = $this->get('daybreak_studios_airbrake.service.airbrake');
     try {
         $airbrake->notify($exception);
     } catch (\Exception $e) {
         $this->get('logger')->error('Airbrake failed', ['exception' => $e]);
     }
     

Tips

1. Context Enrichment:

   • Attach request data dynamically:

     $airbrake->addContext('request', [
         'url' => $request->getUri(),
         'method' => $request->getMethod(),
     ]);
     

2. Environment-Specific Config:

   • Use %kernel.environment% to conditionally enable features:

     daybreak_studios_airbrake:
         enabled: %kernel.environment% == 'prod'
     

3. Testing:

   • Mock the Airbrake service in tests:

     $this->container->set('daybreak_studios_airbrake.service.airbrake', $this->createMock(Airbrake::class));
     

4. Performance:

   • Disable in non-production:

     # config_dev.yml
     daybreak_studios_airbrake:
         enabled: false
     

5. Alternatives:

   • For newer Symfony, consider sentry/sentry-laravel (Laravel) or sentry/sentry-symfony (Symfony).