Raven Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle:

   composer require alexandermatveev/raven-bundle
   

   Update AppKernel.php to register the bundle:

   new AlexanderMatveev\RavenBundle\AlexanderMatveevRavenBundle(),
   

2. Install Assets:

   php bin/console assets:install web --symlink
   

   Verify the asset is available at:

   /web/bundles/alexandermatveevraven/raven.min.js
   

3. First Use Case: Include the script in your base template (e.g., base.html.twig):

   <script src="{{ asset('bundles/alexandermatveevraven/raven.min.js') }}"></script>
   

   Initialize Raven in JavaScript (e.g., app.js):

   Raven.config('YOUR_DSN_HERE').install();
   

Implementation Patterns

Core Workflow

1. Configuration:

   • Override default settings via config.yml (if supported) or environment variables.
   • Example: Set DSN dynamically in app/config/config_prod.yml:

     alexander_matveev_raven:
         dsn: '%env(SENTRY_DSN)%'
     

2. Integration with Symfony:

   • Twig: Pass error context to JavaScript via Twig globals or variables:

     {{ raven_context|json_encode|raw }}
     

   • Controllers: Attach metadata to errors:

     Raven::captureMessage('Failed to process order', [
         'order_id' => $order->id,
         'user_id' => $user->id,
     ]);
     

3. Asset Management:

   • Use Symfony’s asset pipeline for versioning:

     <script src="{{ asset('bundles/alexandermatveevraven/raven.min.js', {'version': '1.0'}) }}"></script>
     

4. Environment-Specific Setup:

   • Disable Raven in dev environment via Twig:

     {% if app.environment == 'dev' %}
         <script>window.Raven = {install: function() {}};</script>
     {% else %}
         {{ include('scripts/raven.js') }}
     {% endif %}
     

Gotchas and Tips

Pitfalls

1. Outdated Dependencies:

   • The bundle uses Raven.js 3.7.0 (released 2015), which may lack support for modern browsers or Sentry features. Verify compatibility with your Sentry server version.
   • Workaround: Manually include a newer raven.js via CDN or bundle it separately.

2. Asset Path Assumptions:

   • The bundle assumes assets are installed to /web/bundles/alexandermatveevraven/. Custom paths may break asset resolution.
   • Fix: Override the asset path in config.yml (if configurable) or symlink manually.

3. No Symfony 3/4+ Support:

   • The bundle targets Symfony 2.x and lacks Flex/auto-wiring support. Manual registration is required.
   • Tip: Fork the bundle or use a modern alternative like symfony/sentry-bundle.

4. Missing Configuration Options:

   • No built-in support for release tracking, environment filtering, or ignoreUrls. Configure via JavaScript:

     Raven.config('DSN', {
         release: '1.0.0',
         environment: 'production',
         ignoreUrls: [/^\/health-check/]
     }).install();
     

Debugging Tips

1. Verify Installation:

   • Check if raven.min.js loads in the browser’s Network tab. 404 errors indicate asset misconfiguration.

2. Test Error Capture:

   • Trigger a JavaScript error (e.g., throw new Error('Test')) and check Sentry for the event. Missing events may indicate:
     • Incorrect DSN.
     • Ad-blockers interfering with Raven.
     • JavaScript errors preventing Raven.install().

3. Log Level:

   • Enable debug logs in app/config/config_dev.yml:

     monolog:
         handlers:
             main:
                 level: debug
     

Extension Points

1. Custom Error Handling:

   • Extend the bundle by overriding the Twig extension or creating a custom event listener for Symfony’s kernel.exception event.

2. Dynamic DSN:

   • Fetch the DSN from an API or database at runtime:

     fetch('/api/sentry-dsn')
         .then(response => response.text())
         .then(dsn => Raven.config(dsn).install());
     

3. Polyfill for Modern Sentry:

   • Replace raven.min.js with @sentry/browser via npm/webpack for up-to-date features.