Sentry Symfony Laravel Package

Getting Started

Read this first: this bundle will not run under Laravel. gcg-it/sentry-symfony registers SentryBundle\SentryBundle, hooks Symfony's KernelEvents (kernel.request, kernel.exception, kernel.terminate) via compiler passes, and expects the Symfony HTTP kernel lifecycle. Laravel bootstraps its own kernel and dispatcher; none of those listeners fire. There is no service provider, no facade, no middleware, no publishable config. For a Laravel team, the day-one task is deciding not to put this in the tree.

The correct dependency is sentry/sentry-laravel. If you are on a hybrid estate with a legacy Symfony service alongside Laravel apps, the Symfony service gets the official sentry/sentry-symfony — not this fork — and Laravel gets sentry/sentry-laravel. Both talk to the same Sentry project if you keep environment, release, and traces_sample_rate conventions aligned.

If you are nonetheless opening this repo (auditing a transitive dep, or inheriting a Symfony service someone else built), the minimum steps are:

1. Establish provenance. Diff composer.json and the tag/branch history against sentry/sentry-symfony. With 0 stars and 0 dependents this is almost certainly an agency fork carrying a patch (older Symfony LTS, a custom transport, a before_send tweak). You need to know what is patched before you can justify it.
2. Test resolution against your Laravel app before believing it installs. composer require gcg-it/sentry-symfony --dry-run, then composer why-not laravel/framework. Laravel pins symfony/* transitives per major; this bundle's constraints may collide and block a future framework upgrade.
3. In a real Symfony app (not Laravel), register SentryBundle\SentryBundle::class => ['all' => true] in config/bundles.php and create config/packages/sentry.yaml:

sentry:
    dsn: '%env(SENTRY_DSN)%'
    options:
        environment: '%kernel.environment%'
        release: '%env(SENTRY_RELEASE)%'
        traces_sample_rate: 0.1
        send_default_pii: false

4. First use case — verify automatic exception capture end-to-end. Add a throwaway controller that throws, hit it in staging (a wrong DSN fails silently, so you need a real send), confirm the event lands with a stack trace, request context, and the right environment/release. Then delete the route. Do the exact same smoke test with sentry/sentry-laravel on your Laravel app so you have a baseline.

Where to look first in the source: DependencyInjection/Configuration.php (the real config surface — usually richer than the README), EventListener/ (what is auto-hooked), and Resources/config/ (service wiring).

Implementation Patterns

The bundle's own pattern (Symfony only, for context when you read the code): an exception listener catches uncaught exceptions at the kernel boundary and reports them; a Monolog handler forwards warnings and above as events; the Hub is available as a service for manual capture. Day-to-day, developers rarely touch the bundle — they write normal Symfony code and errors show up on their own.

The Laravel equivalent you will actually write — one-to-one with the Symfony surface:

Day-to-day patterns you'll reach for (identical in both SDKs, so skills transfer):

• User context for support triage. Attach the authenticated user so support can find "the error that hit this customer":

\Sentry\configureScope(function (\Sentry\State\Scope $scope) use ($user): void {
    $scope->setUser(['id' => $user->id, 'email' => $user->email]);
});

• Tags and breadcrumbs for filtering. Tag by tenant, feature flag, or job name so on-call can slice incidents: \Sentry\setTag('tenant', $tenant->id) and \Sentry\addBreadcrumb(...) around integrations.
• Release tagging in CI. Set SENTRY_RELEASE (or SENTRY_LARAVEL_DSN/SENTRY_RELEASE in Laravel) to the git SHA in your deploy pipeline. Without this, regressions can't be pinned to a deploy.
• Queue and console coverage. In Laravel, sentry/sentry-laravel instruments queue workers and the console kernel. If job failures matter to you (they do), this is a large part of the value.
• Manual capture where you swallow exceptions. Any try/catch that logs-and-continues should \Sentry\captureException($e) first, so the error doesn't vanish from the dashboard.

Hybrid estate workflow: treat the two SDKs as separate dependencies per app, sharing only environment conventions. Do not try to make one package cover both frameworks — that is how teams end up with an observability dependency that silently no-ops on one side.

Gotchas and Tips

• The dominant failure mode is silent non-capture. If someone installs this in a Laravel app expecting automatic error tracking, they get nothing — but they think they're covered until an incident. This is the single worst property of a mis-adopted observability package. Check that a deliberately thrown test exception actually appears in Sentry before trusting any setup.
• DSN no-op. An empty or malformed DSN causes events to be dropped without an error. Validate it at boot; fail loudly in staging/production rather than failing open.
• PII is on by default in places. Request bodies, headers, query strings, and breadcrumbs can all leak into events. Set send_default_pii: false and add a before_send scrubber for anything sensitive (auth headers, tokens, email fields).
• Synchronous transport is an availability risk. Ensure the async/HTTP transport with a timeout is configured, so a Sentry outage cannot add latency to request handling or, worse, block it.
• Recursive capture. If the Sentry client itself throws inside the exception path (bad transport, serialization failure), you can get loops or noise. Guard with a before_send filter or a "Sentry internal error" allowlist.
• Sentry SDK v3 vs v4 is a breaking boundary. Hub/Scope APIs and configuration keys changed. Before pinning this fork, confirm which SDK major it targets and that it matches what sentry/sentry-laravel or a Symfony LTS pins — you don't want the two halves of a hybrid estate on different SDK majors if you ever share a project or a runbook.
• Composer conflicts surface late. laravel/framework pins symfony/* transtively per major. Installing this bundle can resolve today and then block a framework upgrade next quarter with a confusing why-not. Check upfront and record the constraint in the dependency register.
• Quota and cost creep. An unbounded traces_sample_rate, verbose breadcrumbs, or logging at debug through the Monolog handler will burn plan units fast. Sample tracing at 5–10% and be deliberate about which log levels become events.
• Extension points are the options map, not custom container services. Anything exotic (custom transport, event processors, before_send, integrations) is done by configuring options or by adding a service tagged as a Sentry event processor / breadcrumb builder — check the bundle's Resources/config/ for the exact service IDs and tags rather than guessing.
• If this is transitive in your tree, trace it with composer why gcg-it/sentry-symfony and remove it. A Symfony-only fork has no defensible place in a Laravel dependency graph, and the correct replacement (sentry/sentry-laravel) is a first-party package with a release cadence, upstream security backports, and a support path.