Bugsnag Symfony Ext Laravel Package

Getting Started

Minimal Setup

1. Install the Package

   composer require beapp/bugsnag-symfony-ext
   

2. Configure in config/packages/bugsnag_ext.yaml

   bugsnag_ext:
       handled_exceptions:
           - 'App\Exception\LogicException'
       excluded_exceptions:
           - 'App\Exception\NotSoImportantException'
       excluded_http_codes: ["4xx", 301]
   

3. Enable the Bundle Add to config/bundles.php:

   BeApp\BugsnagExt\BugsnagExtBundle::class => ['all' => true],
   

4. First Use Case Test by throwing a LogicException—it should now appear as handled in Bugsnag, while NotSoImportantException is ignored.

Implementation Patterns

Middleware & Listeners

• Forced Handled Exceptions Use handled_exceptions to mark business logic errors (e.g., LogicException) as handled in Bugsnag, avoiding noise in error reports.

  handled_exceptions:
      - 'App\Exception\ValidationFailedException'
  

• Excluding Errors Suppress exceptions like NotFoundHttpException or custom IgnoreMeException:

  excluded_exceptions:
      - 'Symfony\Component\HttpKernel\Exception\NotFoundHttpException'
  

• HTTP Code Filtering Ignore 4xx/301 errors globally (e.g., client-side redirects or validation failures):

  excluded_http_codes: ["4xx", 301, 302]
  

• Session Per Request Enable for request-scoped session data (e.g., tracking user actions):

  session_per_request: true
  

  Note: Requires Symfony’s session component.

Integration Workflows

1. Custom Exception Handling Extend BugsnagExtBundle to add pre-processing:

   // src/EventListener/CustomBugsnagListener.php
   use BeApp\BugsnagExt\Event\BugsnagEvent;
   
   class CustomBugsnagListener implements EventSubscriberInterface {
       public static function getSubscribedEvents(): array {
           return [BugsnagEvent::EXCEPTION => 'onBugsnagException'];
       }
   
       public function onBugsnagException(BugsnagEvent $event) {
           if ($event->getException() instanceof MyCustomException) {
               $event->setHandled(true);
           }
       }
   }
   

   Register in services.yaml:

   services:
       App\EventListener\CustomBugsnagListener:
           tags: ['kernel.event_subscriber']
   

2. Dynamic Configuration Override config via environment variables (e.g., .env):

   BUGSNAG_EXT_HANDLED_EXCEPTIONS="App\\Exception\\PaymentFailedException"
   

Gotchas and Tips

Pitfalls

• Overriding Default Bugsnag Behavior The package modifies Bugsnag’s Symfony integration. Ensure no conflicts with bugsnag/bugsnag-symfony config (e.g., report_callback). Fix: Use priority: high in services.yaml for your listeners.

• Session Per Request Requires Symfony’s Session component. If missing, throws LogicException. Fix: Install symfony/session or disable session_per_request.

• HTTP Code Wildcards excluded_http_codes uses "x" as a wildcard (e.g., "4xx"). Invalid patterns (e.g., "5x") are silently ignored.

• Exception Matching Uses instanceof for handled_exceptions/excluded_exceptions. For interfaces or abstract classes, ensure the FQCN matches exactly.

Debugging

• Verify Configuration Check if settings are loaded via:

  $this->getParameter('bugsnag_ext.handled_exceptions');
  

  Tip: Use dump() in a controller to debug during development.

• Listener Debugging Add logging to CustomBugsnagListener:

  public function onBugsnagException(BugsnagEvent $event) {
      $this->logger->debug('Bugsnag event triggered', ['exception' => $event->getException()]);
  }
  

Extension Points

• Custom Event Subscribers Extend BugsnagEvent to add metadata (e.g., user context):

  $event->addMetadata('custom', ['user_id' => $user->id]);
  

• Middleware Integration Combine with Symfony’s ErrorListener to enrich exceptions before Bugsnag processes them:

  // src/EventListener/ExceptionEnricher.php
  public function onKernelException(GetResponseForExceptionEvent $event) {
      $exception = $event->getThrowable();
      if ($exception instanceof MyException) {
          $event->getRequest()->attributes->set('bugsnag_severity', 'warning');
      }
  }
  

• Conditional Exclusions Dynamically exclude exceptions based on request attributes:

  # services.yaml
  BeApp\BugsnagExt\EventListener\ExclusionListener:
      arguments:
          $excludedCodes: '%env(BUGSNAG_EXT_DYNAMIC_EXCLUDED_CODES)%'
      tags: ['kernel.event_subscriber']