Sentry Extension Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require druidvav/sentry-extension-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       Druidvav\SentryExtensionBundle\DruidvavSentryExtensionBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console druidvav:sentry-extension:install
   

   Edit config/packages/druidvav_sentry_extension.yaml to include your Sentry DSN and project-specific settings.

3. First Use Case Trigger a test event in a controller:

   use Druidvav\SentryExtensionBundle\Sentry\SentryClient;
   
   public function testSentry(SentryClient $sentry)
   {
       $sentry->captureMessage('Test event from Laravel');
       return 'Event sent to Sentry';
   }
   

Key Files to Review

• config/packages/druidvav_sentry_extension.yaml (main config)
• src/Sentry/SentryClient.php (core client class)
• src/EventListener/SentryListener.php (default event listeners)

Implementation Patterns

Core Workflows

1. Event Capture

   // Basic message
   $sentry->captureMessage('User login failed');
   
   // Exception handling
   try {
       // Risky operation
   } catch (\Exception $e) {
       $sentry->captureException($e);
   }
   
   // Structured data
   $sentry->captureMessage('Payment processed', [
       'amount' => $order->amount,
       'user_id' => auth()->id(),
       'status' => 'completed'
   ]);
   

2. Middleware Integration

   // src/Http/Middleware/TrackUserActivity.php
   public function handle($request, Closure $next)
   {
       $response = $next($request);
       $sentry->captureMessage('User accessed: ' . $request->path(), [
           'user_id' => auth()->id(),
           'ip' => $request->ip()
       ]);
       return $response;
   }
   

3. Command-Line Events

   // In a console command
   public function handle()
   {
       try {
           // Command logic
       } catch (\Exception $e) {
           $sentry->captureException($e, [
               'command' => $this->command->getName(),
               'arguments' => $this->argument('input')
           ]);
       }
   }
   

Integration Tips

• Symfony Event Dispatcher Bind to kernel events for automatic tracking:

  # config/packages/druidvav_sentry_extension.yaml
  listeners:
      kernel.exception: ['Druidvav\SentryExtensionBundle\EventListener\SentryListener::onKernelException']
  

• Laravel-Specific Extensions Use the SentryClient facade in service providers:

  public function register()
  {
      $this->app->bind('sentry', function () {
          return new \Druidvav\SentryExtensionBundle\Sentry\SentryClient(
              config('sentry.dsn'),
              config('sentry.options')
          );
      });
  }
  

• Custom Tags/Context Attach metadata globally via config:

  tags:
      environment: 'production'
      application: 'laravel-app'
  

Gotchas and Tips

Common Pitfalls

1. DSN Configuration

   • Ensure the DSN in config/packages/druidvav_sentry_extension.yaml matches your Sentry project.
   • Debug Tip: Use SentryClient::getLastError() to check connection issues.

2. Rate Limiting

   • Sentry has rate limits. For high-volume apps, batch events or use async processing:

     $sentry->captureMessage('High-frequency event', [], ['rate_limit' => 10]);
     

3. Environment-Specific Config

   • Override config per environment:

     # config/packages/dev/druidvav_sentry_extension.yaml
     dsn: '%env(SENTRY_DSN_DEV)%'
     debug: true
     

4. Event Deduplication

   • Use fingerprint to avoid duplicate events:

     $sentry->captureMessage('Failed login', [], [
         'fingerprint' => ['{{ default_user }}', '{{ input_ip }}']
     ]);
     

Debugging Tips

• Log Events Locally Enable debug mode to log events before sending:

  debug: true
  

• Test Events Use the captureMockEvent() method for local testing:

  $mockEvent = $sentry->captureMockEvent('Test event');
  dd($mockEvent->toArray());
  

• Event Listener Debugging Temporarily disable listeners:

  listeners:
      kernel.exception: false
  

Extension Points

1. Custom Event Types Extend SentryClient to add domain-specific methods:

   // app/Sentry/CustomSentryClient.php
   class CustomSentryClient extends \Druidvav\SentryExtensionBundle\Sentry\SentryClient
   {
       public function capturePaymentFailure($payment, \Exception $e)
       {
           $this->captureException($e, [
               'payment_id' => $payment->id,
               'amount' => $payment->amount,
               'gateway' => $payment->gateway
           ]);
       }
   }
   

2. Event Transformers Override event data before sending:

   transformers:
       exception: 'App\Sentry\ExceptionTransformer'
   

3. Async Processing For performance, queue events:

   // In a queue job
   public function handle()
   {
       $sentry->captureMessage('Async event', [], ['queue' => true]);
   }
   

Configuration Quirks

• Breadcrumbs Enable HTTP breadcrumbs for request tracking:

  options:
      send_default_pii: true
      traces_sample_rate: 1.0
  

• Release Tracking Auto-set release version:

  release: '{{ env("APP_VERSION") }}'
  

• Ignored Exceptions Exclude specific exceptions from being captured:

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