Raven Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require classmarkets/raven-bundle ~1.0.0
   

   Add the bundle to config/bundles.php (Symfony 4+) or AppKernel.php (Symfony 2/3):

   new \ClassMarkets\RavenBundle\ClassMarketsRavenBundle(),
   

2. Enable Sentry Integration Ensure your Symfony app is already configured with Sentry (e.g., via sentry/sentry-symfony). The bundle assumes Sentry is active and exceptions are being captured.

3. First Use Case Modify your error template (e.g., templates/bundles/TwigBundle/Exception/error.html.twig) to include the event ID:

   {% if exception is defined %}
       {% set eventId = sentry_event_id(exception) %}
       {% if eventId %}
           <p>Error reported to Sentry: <code>{{ eventId }}</code></p>
       {% endif %}
   {% endif %}
   

Implementation Patterns

Core Workflow

1. Exception Handling Use the Twig function sentry_event_id(exception) in error templates to display Sentry event IDs. Example:

   {% extends 'base.html.twig' %}
   {% block content %}
       <h1>Error: {{ exception.message }}</h1>
       {% set eventId = sentry_event_id(exception) %}
       {% if eventId %}
           <p>Sentry Event ID: <code>{{ eventId }}</code></p>
       {% endif %}
   {% endblock %}
   

2. Programmatic Access Retrieve event IDs in controllers/services via the service container:

   $eventId = $this->get('cm_raven.sentry_event_recorder')->getEventIdForException($exception);
   

3. Custom Error Pages Extend the default error template to include the event ID in custom error pages (e.g., for APIs or user-friendly messages).

Integration Tips

• Symfony Monolog Bridge: If using sentry/sentry-monolog, ensure the bundle is loaded after the Monolog bundle to avoid conflicts.
• Twig Extensions: The bundle registers a Twig extension automatically. Override it in your app if you need custom logic:

  # config/packages/twig.yaml
  twig:
      extensions:
          - ClassMarkets\RavenBundle\Twig\SentryEventExtension
  

• API Responses: For JSON APIs, include the event ID in error responses:

  return $this->json([
      'error' => $exception->getMessage(),
      'sentry_event_id' => $this->get('cm_raven.sentry_event_recorder')->getEventIdForException($exception),
  ], 500);
  

Gotchas and Tips

Pitfalls

1. No Event ID for Non-Sentry Exceptions The bundle only works if the exception was captured by Sentry. If no event ID exists, sentry_event_id() returns null. Always check for its existence:

   {% if sentry_event_id(exception) %}
       {# Render event ID #}
   {% endif %}
   

2. Symfony Version Compatibility The bundle is designed for Symfony 2/3. If using Symfony 4+, ensure the cm_raven.sentry_event_recorder service is autowired correctly (it may require manual registration in config/services.yaml):

   services:
       cm_raven.sentry_event_recorder:
           class: ClassMarkets\RavenBundle\Sentry\EventRecorder
           arguments: ['@sentry.client']
   

3. Caching Issues If event IDs disappear after deployment, clear Symfony’s cache:

   php bin/console cache:clear
   

Debugging

• Check Sentry Configuration: Verify Sentry is properly initialized in config/packages/sentry.yaml or app/config/config.yml.
• Log Event IDs: Debug the recorder service:

  $recorder = $this->get('cm_raven.sentry_event_recorder');
  $this->logger->debug('Event ID for exception:', ['id' => $recorder->getEventIdForException($exception)]);
  

• Twig Debugging: Enable Twig debug mode to inspect the sentry_event_id function:

  # config/packages/dev/twig.yaml
  twig:
      debug: true
  

Extension Points

1. Custom Event ID Storage Override the EventRecorder service to store event IDs in a custom location (e.g., session or database):

   // src/Service/CustomEventRecorder.php
   class CustomEventRecorder extends \ClassMarkets\RavenBundle\Sentry\EventRecorder {
       public function getEventIdForException(\Exception $exception) {
           // Custom logic here
       }
   }
   

   Then update services.yaml to use your class.

2. Twig Function Aliases Add a shorter Twig alias for sentry_event_id in your app’s Twig config:

   twig:
       globals:
           sentry_id: '@cm_raven.sentry_event_recorder'
   

   Usage:

   {{ sentry_id.getEventIdForException(exception) }}
   

3. Event ID in Logs Extend the bundle to log event IDs alongside exceptions using Monolog:

   $this->get('monolog.logger')->info('Exception with Sentry ID', [
       'exception' => $exception,
       'sentry_id' => $recorder->getEventIdForException($exception),
   ]);