Sentry Laravel Package

Getting Started

Before installing, read the package's composer.json rather than the README — this bridge was last released in mid‑2016, so its constraints almost certainly target PHP 5.6/7.0 and Laravel 5.1–5.4. On anything newer you will need --ignore-platform-reqs or a fork; verify the pinned sentry/sentry SDK major version first, because the 1.x and 2.x client APIs are not compatible.

Minimal setup:

1. composer require alt-three/sentry
2. Register AltThree\Sentry\SentryServiceProvider::class in config/app.php (Laravel 5.5 package auto-discovery almost certainly is not supported at this release date).
3. php artisan vendor:publish --provider="AltThree\Sentry\SentryServiceProvider" to get config/sentry.php.
4. Put SENTRY_DSN=https://[email protected]/... in .env and confirm the config file reads from env('SENTRY_DSN').

Where to look first:

• The service provider — it tells you exactly what is bound into the container (client, hub, or a logger handler) and what it hooks into.
• config/sentry.php — DSN, environment/release tags, and any minimum log level.
• App\Exceptions\Handler — the natural integration point.

The first thing to wire up is the exception handler. In Handler::report(Exception $e), guard with $this->shouldReport($e) and hand the exception to the client the package binds. Confirm it works by throwing a RuntimeException from a route and checking that the event id returned by the client is non‑null and the event appears in Sentry within a few seconds.

Implementation Patterns

Exception handler as the single funnel. Keep reporting in report() and never in render(). Use shouldReport() plus the $dontReport array to filter validation and 404-type noise rather than filtering inside Sentry. If the package exposes a log handler, let Log::error() flow through it and avoid calling the client manually for the same exception — otherwise you get duplicate events.

User and request context. The bridge gives you a client; contextualizing is your job. Set user context (id, email, IP) and tags (route name, environment, release) once per request — a middleware after StartSession is the cleanest place — rather than inside the handler. Scrub anything regulated: request bodies, auth headers, and query strings frequently end up in "extra" data if you pass $request wholesale.

Reporting outside HTTP. For queued jobs, report from failed() or wrap handle(); the container binding exists in the worker, but per‑request context does not follow the job. For Artisan commands, report in handle() or wrap Artisan::call(). In long-running workers (queue, Octane‑era setups), reset user/tag context at the start of each unit of work — otherwise user A's context sticks to user B's exception.

Environment and release tagging. Set environment and release from config driven by env vars. On 2016-era Sentry this is often the only way to correlate a regression with a deploy, since source map and commit tracking did not exist yet.

Testing. The cheapest reliable approach is to blank the DSN in phpunit.xml (<env name="SENTRY_DSN" value=""/>) so the client no‑ops, rather than mocking a facade. If you need assertions, rebind the client in a test service provider or use a fake transport.

Gotchas and Tips

• Archived and unmaintained. No security patches, no SDK upgrades, zero dependents. Treat it as a vendored snippet: fork it or, more realistically, plan a migration to sentry/sentry-laravel and use this package only on legacy branches.
• Never run both. This bridge and sentry/sentry-laravel both register handlers and both read SENTRY_DSN; you will double-report every exception and double your quota.
• SDK version confusion. A 2016 bridge likely sits on sentry/sentry 1.x, whose classes are Sentry\Client/Sentry\State\Hub (and Raven_Client in the very oldest paths). Copying modern Sentry snippets — \Sentry\init(), \Sentry\captureException() — into this codebase will silently do nothing.
• Synchronous transport. The default transport blocks the request. If Sentry is unreachable, every exception adds connection-timeout latency on top of an already-failing request. Check whether the version supports a timeout config and set it low.
• Recursion. If your reporting code itself throws (bad context serialization, a closure in exception args), you can loop. Wrap the capture call in its own try/catch and swallow.
• Config cache. php artisan config:cache freezes the DSN and environment into bootstrap/cache/config.php. After changing .env, run config:clear — a missing DSN after a deploy is almost always this.
• Debugging a silent failure. captureException() returning null means the client never sent. Test with a throw in php artisan tinker, then check: DSN scheme (https, matching project key), CA bundle on old PHP (curl.cainfo), and outbound firewall rules. Enable the SDK's internal logger if the version has one.
• Extension points. Because it is just a container binding, the most useful lever is rebinding the client or transport in a provider registered after the package's provider — that lets you swap in a null transport in local/testing, or route different environments to different DSNs without touching the package.
• PII leakage is the real risk. Old Sentry SDKs serialized aggressively. Audit what ends up in "extra" before you enable this on customer-facing traffic, and prefer explicit tags over dumping request objects.