Laravel Sentry Laravel Package

Getting Started

This package is a thin decorator, not a full Sentry integration. It assumes sentry/sentry-laravel is already installed and configured; the package's job is to run middleware that pushes request/user context onto the Sentry scope so every event carries it. Verify that assumption against the source before building on it — with 1 star and 0 dependents, the README is the only contract.

Minimum viable setup:

composer require sentry/sentry-laravel zing/laravel-sentry
php artisan sentry:publish --dsn="${SENTRY_DSN}"

Then publish the package's own config/provider assets if it ships any:

php artisan vendor:publish --provider="Zing\LaravelSentry\SentryServiceProvider"

Where to look first, in order: the package's middleware class (that's the entire feature surface), its service provider (to see what it binds or publishes), then config/sentry.php for the SDK settings that govern when context is actually attached.

Register the middleware globally so it applies to every request — that's the intended usage:

// bootstrap/app.php (Laravel 11+)
->withMiddleware(function (Middleware $middleware) {
    $middleware->append(\Zing\LaravelSentry\Middleware\SentryContext::class);
})

The first use case you should validate: log in, throw a deliberate exception in a controller, and confirm the resulting Sentry event has the user's id/email and a request identifier attached. If it doesn't, the middleware ran before auth, or the DSN isn't reaching the SDK.

Implementation Patterns

Treat this as scope enrichment, not exception capture. sentry/sentry-laravel already hooks the handler and queue worker. This package only calls into Sentry\configureScope() to set tags, user, and extra context. If your error events are missing entirely, the bug is upstream of this package.

Global middleware for baseline context, route groups for domain context. Append the middleware globally for user + request id, then layer domain tags (tenant id, feature flag, plan tier) either via a small custom middleware or a Scope callback in a service provider:

\Sentry\configureScope(function (\Sentry\State\Scope $scope) use ($tenant) {
    $scope->setTag('tenant', $tenant->slug);
    $scope->setContext('billing', ['plan' => $tenant->plan]);
});

Because callbacks compose, your own scope work merges cleanly with whatever the middleware sets — last write wins per key.

Wire a correlation id through both logs and Sentry. Generate (or accept) a request id early, expose it as a response header, and set it as a Sentry tag with the same string you feed your Monolog processor. This is the highest-value payoff of the package: you can jump from a Sentry issue to the exact log lines for that request.

Fall back for guests. In a global middleware, $request->user() is frequently null (webhooks, health checks, login screen). Make sure the implementation tolerates that instead of throwing — and consider setting a session or request id as the "user" surrogate so anonymous errors are still groupable.

Console and queue jobs don't go through HTTP middleware. Context for jobs must come from sentry/sentry-laravel's queue integration or from manual scope calls inside handle(). Don't assume parity between HTTP errors and queued-job errors.

Test scope assertions. Point the SDK at a TestClient in your test bootstrap and assert on captured events rather than mocking the middleware — you want to know what actually landed on the scope.

Gotchas and Tips

Middleware ordering is the number one failure mode. Global middleware runs before route-level auth middleware resolves. If the session hasn't started or Authenticate hasn't run, $request->user() is null and you'll ship events with empty user context — silently. Either register the context middleware in the web group after StartSession/Authenticate, or defer user resolution on the scope until the event is built.

PII ships by default. User emails and IPs are the whole point of the package and also the thing your DPO will ask about. Add a before_send hook in config/sentry.php to strip or hash fields, and document the decision in the repo.

Silent no-op without a DSN. Local and CI environments will run the middleware happily against an uninitialized hub. Nothing errors, so a broken scope callback can go unnoticed until production. If context correctness matters, add an integration test with a TestClient.

Transactions need sampling. Context attaches to error events regardless, but if traces_sample_rate is 0 the enrichment never appears on performance data. Set it explicitly rather than relying on the default.

Check for duplication with the SDK. Recent sentry/sentry-laravel versions attach user context themselves. Running both means doubled tags or one overwriting the other. Decide which layer owns user context and remove the other.

Pin exact versions and read the diff on upgrade. Single maintainer, one star, no dependents, and a release date that doesn't match typical cadence — verify the tag's contents against composer.json and the changelog each bump. The middleware is likely a few dozen lines: vendor it into app/Support/ and you remove an entire dependency risk while keeping the behavior. That's a reasonable call here; the tradeoff is losing upstream fixes you'd have to track manually.

Debug with the hub. Sentry\SentrySdk::getCurrentHub()->getLastEventId() in the exception handler confirms an event was sent; a TestClient dump shows the scope snapshot. Enable the SDK's logger temporarily if context is silently missing, and check whether configureScope callbacks are registered before the hub is initialized — callbacks registered too early get discarded.