Raven Laravel Package

Getting Started

rcrowe/raven sits between your application and Sentry: instead of reporting exceptions synchronously inside the request lifecycle (which adds latency and can fail the request if Sentry is slow or down), it pushes the report onto a Laravel queue and lets a worker talk to Sentry.

Minimal setup:

1. Install via Composer:

   composer require rcrowe/raven
   

2. Publish the config (the provider is auto-discovered on modern Laravel):

   php artisan vendor:publish --provider="Rcrowe\Raven\RavenServiceProvider"
   

3. Set your Sentry DSN and queue connection in .env:

   SENTRY_DSN=https://<key>@sentry.io/<project>
   RAVEN_QUEUE_CONNECTION=redis
   RAVEN_QUEUE=default
   

4. Make sure a worker is running: php artisan queue:work.

Where to look first:

• config/raven.php — DSN, queue connection/name, environment, and which handlers/levels are queued.
• app/Exceptions/Handler.php — this is where you bridge Laravel's report() into the package.
• The package's queue job class — read it before customizing, so you understand what is (and isn't) serialized onto the payload.

First use case: take a noisy production app where every report() call currently makes an outbound HTTP call to Sentry, and route those reports through the queue so request latency is decoupled from Sentry's availability. A good smoke test is to throw new \Exception('raven test') from a tinker session and confirm a job appears on your queue before the Sentry event shows up.

Implementation Patterns

Wrapping the default handler. The cleanest integration is in app/Exceptions/Handler.php. Rather than replacing Laravel's report(), call the package's queued reporter in addition to (or instead of) the parent, and gate on whether the exception should be reported:

public function report(Throwable $e)
{
    if ($this->shouldReport($e)) {
        app(\Rcrowe\Raven\Raven::class)->captureException($e);
    }

    parent::report($e);
}

Be deliberate about not calling parent::report() if the parent is also configured to send to Sentry — otherwise you double-report.

Middleware for request context. Queue jobs run outside the request, so the Sentry event loses the user, URL, and headers that were in scope. Capture those before dispatch (in a middleware or in the handler) and pass them as "extra"/"tags"/"user" context, then reattach them inside the job before calling Sentry.

Background reporting for non-exception events. The package is not only for exceptions — use it for captureMessage at warning/error levels for things like failed third-party API calls, webhook signature failures, or degraded dependency checks. This is where a queued reporter really shines: you can be liberal with breadcrumbs without every one of them costing request time.

Sampling / rate limiting. For high-traffic endpoints, wrap the reporter call with a sampling check (e.g. if (mt_rand(1, 100) <= 10)) or RateLimiter keyed by exception class + route. Queuing solves latency but not volume; a hot loop can still flood the queue.

Testing. Because reporting is async, use Queue::fake() and assert the Raven job was pushed rather than asserting Sentry received anything. For the job itself, swap the Sentry client for a mock and assert captureException was called with expected context. This keeps tests fast and offline.

Gotchas and Tips

• A queue worker is now part of your error pipeline. If the worker is down, exceptions vanish silently. Monitor queue depth and failed jobs, and consider a dead-letter alert — this is the single biggest operational risk of the pattern.
• Exceptions don't always serialize cleanly. Closures, resources, and some vendor exception objects can break job serialization. Prefer capturing the exception class, message, code, file/line, and a trimmed stack trace rather than passing the live Throwable when the object is exotic.
• Lost context is the default. By the time the job runs, auth(), request(), and session are gone. Anything you want on the Sentry event must be explicitly captured and rehydrated — don't assume Request::fullUrl() works inside the job.
• DSN and environment mismatches are the classic first-hour bug. SENTRY_DSN empty → the reporter no-ops quietly; APP_ENV=local with a production DSN → noise in the wrong project. Log once at boot if the DSN is missing rather than failing silently.
• Watch for SDK drift. The package targets an older Sentry PHP client (the "Raven" era) than sentry/sentry-laravel uses today. Pin versions and check compatibility before upgrading Laravel or the Sentry SDK; newer Sentry APIs may not be exposed through the package.
• Failed-report retries can duplicate events. Configure tries and backoff on the job consciously; Sentry will dedupe by event fingerprint, but you can still inflate event counts. Use $job->delete() on permanent 4xx-style failures rather than retrying into a timeout.
• Extension point worth knowing: the package's job/handler is the place to add cross-cutting behavior — enriching payloads with deploy SHA, tenant ID, or user context for every report — rather than scattering that logic through controllers.
• Debugging tip: set the queue connection to sync temporarily to reproduce reporting issues in the request path; once it works there, switch back and verify the real worker picks up jobs with queue:work --once --tries=1.