Sentry Extension Bundle Laravel Package

Getting Started

Minimal Setup

1. Requirements & Installation This is a Symfony bundle (not a Laravel package) — it ships a DI extension and kernel event listeners. As of v1.3.0 the extension class extends Symfony's public Symfony\Component\DependencyInjection\Extension\Extension, so the bundle boots cleanly on modern Symfony (4.4 / 5.x / 6.x) without depending on the removed HttpKernel\DependencyInjection\Extension import.

   composer require druidvav/sentry-extension-bundle
   

   Register in 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. Smoke Test the Wiring Before writing any capture code, confirm the container loads the extension (this is the single fastest way to catch a bad upgrade or a malformed YAML tree):

   php bin/console debug:config druidvav_sentry_extension
   

4. 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 my app');
       return 'Event sent to Sentry';
   }
   

Key Files to Review

• config/packages/druidvav_sentry_extension.yaml (main config)
• src/DependencyInjection/DruidvavSentryExtensionExtension.php (DI extension — changed in v1.3.0)
• 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 / Kernel Request Listener Integration

   // src/EventSubscriber/TrackUserActivitySubscriber.php
   public function onKernelResponse(ResponseEvent $event)
   {
       $request = $event->getRequest();
       $this->sentry->captureMessage('User accessed: ' . $request->getPathInfo(), [
           'user_id' => $this->tokenStorage->getToken()?->getUserIdentifier(),
           'ip' => $request->getClientIp()
       ]);
   }
   

3. Command-Line Events

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

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']
  

• Service Autowiring The SentryClient is registered as a container service by the bundle extension, so prefer constructor injection over manually building it:

  public function __construct(private SentryClient $sentry) {}
  

• Custom Tags/Context Attach metadata globally via config:

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

Gotchas and Tips

Common Pitfalls

1. Symfony Version Compatibility (v1.3.0)

   • v1.3.0 switches the bundle's DI extension to the public DependencyInjection\Extension\Extension base class to drop the removed HttpKernel import. Practically: before v1.3.0 the bundle could fail at container compile-time on Symfony 5+/6 with a Class "Symfony\Component\HttpKernel\DependencyInjection\Extension" not found fatal — the "extension behavior" was fine, only the parent class was gone.
   • Upgrading is a non-breaking, config-compatible change: no YAML keys moved, no service IDs renamed, no new required options. Existing druidvav_sentry_extension.yaml files keep working unchanged.
   • After upgrading, run php bin/console cache:clear and php bin/console debug:config druidvav_sentry_extension — if the extension didn't register, debug:config errors immediately instead of failing on the first request.
   • No action needed if your app is pinned to Symfony < 4.4; the new base class exists on those versions too.

2. DSN Configuration

   • Ensure the DSN in config/packages/druidvav_sentry_extension.yaml matches your Sentry project.
   • Debug Tip: Enable debug: true and check the container-level error first; a missing DSN usually surfaces as "no events delivered," not as an exception.

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

• Verify the Extension Loaded (regression test for the v1.3.0 change)

  php bin/console debug:config druidvav_sentry_extension
  php bin/console debug:container druidvav_sentry_extension
  

  If these fail while other commands work, the bundle registration in config/bundles.php is the culprit, not the Sentry code.

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

  debug: true
  

• Event Listener Debugging Temporarily disable listeners:

  listeners:
      kernel.exception: false
  

Extension Points

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

   // src/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
           ]);
       }
   }
   

   Alias the bundle's service ID to your class in config/services.yaml so autowiring picks it up.

2. Event Transformers Override event data before sending:

   transformers:
       exception: 'App\Sentry\ExceptionTransformer'
   

3. Async Processing For performance, queue events:

   // In a Messenger handler
   public function __invoke(SentryEventMessage $message)
   {
       $this->sentry->captureMessage($message->getText(), [], ['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'