Raven Laravel Package

Getting Started

Install and register. This package predates Laravel package auto-discovery, so registration is manual — both the provider and the facade alias go in config/app.php.

composer require jenssegers/raven

// config/app.php
'providers' => [
    // ...
    Jenssegers\Raven\RavenServiceProvider::class,
],

'aliases' => [
    // ...
    'Raven' => Jenssegers\Raven\Facades\Raven::class,
],

Publish the config and set the DSN in .env:

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

SENTRY_DSN=https://<public-key>@sentry.io/<project-id>

Where to look first. Read the published config/raven.php before writing any code — it is the whole surface area of the package. Pay attention to dsn, environment, the levels / handler keys that control whether the Monolog bridge is wired in, and any breadcrumbs or processors settings. That file answers 90% of "why isn't my event showing up" questions.

First use case — uncaught exceptions. With the provider registered, Laravel's exception handler is hooked and uncaught exceptions report to Sentry automatically. The fastest verification is a throwaway route:

Route::get('/_boom', function () {
    throw new \RuntimeException('Sentry smoke test');
});

Hit it, confirm the event lands in Sentry with a stack trace and request context, then delete the route. If nothing arrives, check APP_DEBUG/APP_ENV gating and confirm the DSN is actually resolving — see the Gotchas section.

Second-most-common first task: manually reporting a caught exception you don't want to rethrow.

try {
    $this->chargeCard($order);
} catch (\Throwable $e) {
    app('raven')->captureException($e); // or Raven::captureException($e)
    return $this->fallback($order);
}

Implementation Patterns

Attach user context at the request boundary. Blanket "something broke" events are nearly useless for triage. Set the user once, high up, so every exception during that request carries it. A middleware is the natural home:

public function handle($request, Closure $next)
{
    if ($user = $request->user()) {
        app('raven')->user_context([
            'id'    => $user->id,
            'email' => $user->email,
        ]);
    }

    return $next($request);
}

Keep the payload to identifiers and, at most, email. Do not dump the full model — that's an accidental PII pipeline into a third-party vendor.

Tag by release and environment. environment belongs in config, but release (a git SHA or version string) is what lets you answer "did this start after deploy?" Set it per-environment at boot:

app('raven')->tags_context([
    'release' => trim(shell_exec('git rev-parse --short HEAD')),
    'queue'   => app()->runningInConsole() ? 'cli' : 'web',
]);

For queue workers, the queue tag is the difference between "the web tier is down" and "one bad job is retrying forever" — an ambiguity that costs real triage minutes.

Use the Monolog bridge for error-level logs, not for everything. If you enable the log handler, be deliberate about which channel it's attached to. Attaching it to your default stack means every Log::error() — including ones you already handle gracefully — becomes a Sentry event and eats quota. A common shape is a dedicated channel:

// config/logging.php
'sentry' => [
    'driver'  => 'monolog',
    'handler' => Jenssegers\Raven\Handlers\RavenHandler::class,
    'level'   => 'error',
],

and then Log::channel('sentry')->error(...) at the handful of places where an alert is genuinely warranted.

Report from report() for domain exceptions. Rather than sprinkling captureException at every catch site, override report() in app/Exceptions/Handler.php for your own exception types. That keeps error routing in one place and composes cleanly with dontReport:

public function report(Exception $e)
{
    if ($e instanceof \App\Exceptions\PaymentFailedException) {
        app('raven')->captureException($e);
    }

    parent::report($e);
}

Add breadcrumbs before risky operations. Breadcrumbs turn "exception on line 83" into a narrative. A few well-placed ones around integrations pay for themselves:

app('raven')->breadcrumb([
    'category' => 'integration',
    'message'  => 'Calling payments API',
    'level'    => 'info',
    'data'     => ['order_id' => $order->id],
]);

Stack, don't replace, your log driver. The integration should be additive. Your file/stderr channel stays the source of truth for local development and tail -f; Sentry is the alerting layer. Don't let enabling the package remove your ability to reproduce an issue on your own machine.

Sanity-check in a console command. Because this package reports on the CLI path too, verify Artisan and queued jobs separately from web requests — they have different context (no HTTP request, no user unless rehydrated from the job).

Gotchas and Tips

Silent no-ops when the DSN is empty. The client generally won't blow up without a DSN; it just does nothing. That's the right production behaviour (monitoring must not break the app) but a terrible debugging experience — a typo'd .env key looks identical to a working install. Always smoke-test with a deliberate throw.

config:cache hides your .env edits. If you set SENTRY_DSN and nothing changes, you almost certainly have a cached config from a previous deploy. php artisan config:clear first, then re-cache. This burns more engineers than any other single issue with Laravel packages of this vintage.

APP_DEBUG=true can suppress reporting locally. In debug mode, Laravel renders the Whoops/ignition page and some integrations skip shipping the event. Always verify against APP_ENV=production APP_DEBUG=false in a staging environment — testing the exception path in local tells you nothing.

Synchronous transport is the big one. The Raven client sends inline by default. During an error storm you get a network round-trip per failing request, which turns a database blip into a sustained outage and a Sentry bill spike. Mitigations, in order of preference: (1) migrate off the package to sentry/sentry-laravel and get its async/sampling behaviour; (2) if you must stay, enable whatever sampling your config exposes and set a low rate; (3) at absolute minimum, ensure the client has a short timeout so a slow Sentry endpoint can't stall requests. Never let the error reporter become the secondary failure domain.

Don't report exceptions you already handle. Every catch block that logs and captures produces duplicates for events you've decided are non-incidents. Use dontReport for expected exceptions (ValidationException, ModelNotFoundException, auth failures) or you train the team to ignore alerts.

PII leaks via request context. The package captures request context — including, depending on configuration, request bodies. Check the processors config and scrub password, token, card, and Authorization fields before this ever runs against a production user base. This is a compliance issue, not a hygiene issue.

No Octane or long-lived-worker awareness. Container state persists across requests under Octane, and stale user/breadcrumb context from request N will appear on the event for request N+1. If you run Octane, either reset context in a middleware's terminate or don't run this package — the failure mode is misattributed PII, which is worse than no monitoring.

The error path itself can throw. raven/raven predates PHP 8.x deprecation hygiene; expect deprecation noise and, worse, occasional fatals inside the reporter. Wrap any explicit captureException call sites in a defensive layer if you're on modern PHP, and remember that a fatal in the error handler takes down the request that was otherwise recovering.

Extension points are narrower than they look. The practical hooks are (a) config processors for scrubbing, (b) a custom Monolog handler if you need different level mapping, and (c) a service-container binding override if you need to decorate the client. Everything else requires forking, which brings you to the next point.

Don't fork it "to keep it alive" without an owner. This package is unmaintained and superseded by sentry/sentry-laravel. An unowned fork sits inline on the exception path of every request with nobody patching it — the worst of both worlds. If you're staying for a genuine reason (PHP 5.6 pin, self-hosted Sentry on the Raven protocol, app being retired), pin exact versions, add a comment pointing at the remediation ticket, and name the maintainer.

Know the migration shape before you need it. It's close to one-to-one, which makes the eventual PR small: provider + facade → auto-discovered provider and Sentry\Laravel\Facades\Sentry; RavenHandler → the sentry channel in config/logging.php; captureException → Sentry\captureException; config keys carried across; and raven/raven plus this package removed in the same PR so the old SDK can't be silently re-resolved by a transitive requirement. Write that ticket now, even if you don't schedule it.

Zero ecosystem signal is itself a data point. With no downstream dependents, there's no Stack Overflow corpus for the exact Laravel/PHP combination you're running, and no crowd-sourced bug reports. Budget for figuring out problems yourself — that cost belongs in the decision, not the surprise column.