Oro Bugsnag Laravel Package

Getting Started

Minimal Setup

1. Install the Package

   composer require allies/oro-bugsnag
   

   Ensure your project meets the requirements (oro/platform:2.*, PHP ≥5.6).

2. Configure BugSnag Add the bugsnag/bugsnag-symfony bundle to config/bundles.php:

   return [
       // ...
       Bugsnag\Symfony\BugsnagBundle::class => ['all' => true],
   ];
   

3. Environment Configuration Add BugSnag API key to .env:

   BUGSNAG_API_KEY=your_api_key_here
   

4. Enable in OroCRM Register the service in config/packages/oro_platform.php (or equivalent OroCRM config):

   imports:
       - { resource: "@OroBugsnagBundle/Resources/config/services.yml" }
   

5. First Use Case Trigger an exception to verify integration:

   throw new \RuntimeException('Test error for BugSnag');
   

   Check BugSnag dashboard for the reported error.

Implementation Patterns

Workflow Integration

1. Automatic Error Capture The package leverages Monolog handlers to auto-capture exceptions/errors. No manual instrumentation needed for most cases.

2. Custom Error Handling Extend OroCRM’s exception handling to include BugSnag:

   // app/config/config.php (or equivalent)
   'oro_exception_handler':
       handler: 'oro_bugsnag.exception_handler'
   

3. Contextual Error Reporting Attach custom metadata (e.g., user ID, request data) via BugSnag’s addTab() or setContext():

   Bugsnag::notifyException($exception, function($report) {
       $report->addTab('User', ['id' => $userId, 'email' => $userEmail]);
   });
   

4. Conditional Reporting Filter errors by severity or environment:

   # config/packages/bugsnag.yaml
   bugsnag:
       enabled: '%kernel.debug% ? false : true'  # Disable in dev
       release_stage: '%env(BUGSNAG_RELEASE_STAGE)%'
   

5. OroCRM-Specific Events Hook into OroCRM events (e.g., oro_integration.connect) to log integration failures:

   $eventDispatcher->addListener('oro_integration.connect', function($event) {
       if ($event->hasError()) {
           Bugsnag::notifyException($event->getError());
       }
   });
   

Gotchas and Tips

Pitfalls

1. Deprecated Dependencies

   • The package relies on bugsnag/bugsnag-symfony:1.*, which may lack support for newer PHP/Monolog versions. Test thoroughly.
   • Workaround: Use a compatible fork or patch the bundle if needed.

2. OroCRM-Specific Quirks

   • OroCRM’s legacy Monolog setup may conflict with BugSnag’s handlers. Ensure the oro_bugsnag.monolog_handler is registered last in the chain.
   • Debugging: Check var/log/dev.log for Monolog errors if reports fail silently.

3. API Key Exposure Hardcoding BUGSNAG_API_KEY in .env is secure, but ensure it’s not committed to version control.

   • Tip: Use environment variables or a secrets manager for production.

4. Release Stage Mismatch BugSnag’s releaseStage must match your deployment environment (e.g., production, staging). Misconfiguration may lead to duplicate reports.

   • Fix: Set dynamically via .env:

     BUGSNAG_RELEASE_STAGE=${APP_ENV:-production}
     

Debugging Tips

1. Verify Handler Registration Check if the BugSnag handler is active:

   php bin/console debug:container oro_bugsnag.monolog_handler
   

   Should return the handler’s configuration.

2. Test Locally Force an error in a controller to confirm reports:

   public function testBugsnag() {
       throw new \LogicException('Test BugSnag');
   }
   

3. Log Level Filtering Exclude DEBUG logs from BugSnag by configuring the handler’s level:

   bugsnag:
       monolog_level: ERROR  # Only report ERROR and above
   

Extension Points

1. Custom Error Formatting Override the OroBugsnagBundle\Handler\BugsnagHandler to modify payloads:

   // src/OroBugsnagBundle/Handler/CustomBugsnagHandler.php
   class CustomBugsnagHandler extends BugsnagHandler {
       public function handle(array $record) {
           $record['extra']['custom_field'] = 'value';
           parent::handle($record);
       }
   }
   

2. Event-Based Reporting Listen to OroCRM events (e.g., oro_entity.update) to report business logic errors:

   $eventDispatcher->addListener('oro_entity.update', function($event) {
       if ($event->hasError()) {
           Bugsnag::notify($event->getError(), [
               'entity' => $event->getEntityClass(),
               'action' => 'update'
           ]);
       }
   });
   

3. Breadcrumbs for Debugging Add contextual breadcrumbs to trace user actions leading to errors:

   Bugsnag::leaveBreadcrumb('User clicked', ['button' => 'submit']);