Filament Sentry Laravel Package

Getting Started

awcodes/filament-sentry wires Sentry into a Filament panel so the exceptions your admin users hit actually reach Sentry — tagged with the panel and, critically, the authenticated Filament user. It is a thin, opinionated layer, not a replacement for sentry/sentry-laravel; think of it as the glue that makes Sentry useful inside the admin.

Minimal path:

1. composer require awcodes/filament-sentry — note that 2.x targets Filament v4. If you are still on v3, stay on the 1.x line; see Gotchas.
2. Publish what the package ships (config, and migrations if you intend to drive settings from the UI):

   php artisan vendor:publish --tag="filament-sentry-config"
   php artisan vendor:publish --tag="filament-sentry-migrations"
   php artisan migrate
   

3. Register the plugin on the panel(s) you want instrumented, in your AdminPanelProvider:

   ->plugin(FilamentSentryPlugin::make())
   

4. Set SENTRY_LARAVEL_DSN in .env (or configure it through the package's settings surface, depending on which mode you chose when publishing).

Where to look first: the plugin class itself (FilamentSentryPlugin) for the fluent configuration API, then the published config file for the knob-by-knob defaults. The repository's workbench/ app is the canonical reference — it is a real Filament panel with the plugin installed, and it's the fastest way to see the intended wiring end to end. tests/ will show you exactly which behaviours are contractually guaranteed versus incidental.

First use case worth proving out: log into your panel as a normal (non-super-admin) user, throw an exception from a page or action, and confirm in Sentry that (a) the event arrived, (b) the user is attached, and (c) the panel/resource context is identifiable. If any of those three are missing, stop and fix it before rolling out — the value of this package is entirely in that context.

Implementation Patterns

Environment-first configuration. For most teams the right pattern is: DSN and sample rate from .env, everything else from the published config file, and the database-backed settings surface disabled or restricted to super-admins. Settings-in-the-database is convenient for a single-tenant internal tool and a liability for anything multi-tenant or audited — an admin with panel access can silently turn off error reporting.

Register per panel, not globally. If you have separate AdminPanelProvider and AppPanelProvider, register the plugin only where you want it. Registering on a public-facing panel means end-user traffic drives your Sentry quota and you inherit PII concerns you probably did not sign up for.

Lean on the user context. The main day-to-day payoff is that Sentry issues arrive already attributed to a Filament user. Make sure your User model is what the panel authenticates with, and verify the identifying field Sentry receives is something you're comfortable storing in a third party — an email or a ULID, not a full name and phone number.

Treat it as one layer in a stack. Pair it with sentry/sentry-laravel's own breadcrumbs and performance tracing rather than expecting this package to do it. Configure release/version tagging (SENTRY_RELEASE) in your deploy pipeline; the plugin does not solve release tracking for you, and untagged issues are near-useless after the first week.

Local development. Leave the DSN empty locally. The package should no-op cleanly, but confirm that for yourself rather than assuming — a plugin that throws on a missing DSN will ruin every php artisan serve session.

Test the integration, not the vendor. Write one test that asserts the plugin registers and the settings page is reachable/authorised. Do not write tests that assert Sentry received an event; mock the hub instead.

Gotchas and Tips

2.x is a Filament v4 release. The "start of 2.x version" commit is the headline here — this is a new major aligned to Filament v4, and a major bump on a Filament plugin almost always means the v3-era plugin registration and any overridden views/pages will not carry over unchanged. Pin the constraint deliberately ("awcodes/filament-sentry": "^2.0" with filament/filament: ^4.0) and read the diff between v2.0.0 and v1.x before upgrading an existing install. Do not let a composer update decide this for you.

v2.0.1 itself is small. The two substantive commits are 2.x housekeeping — merging the 2.x branch forward and switching the workbench UserResource to ShieldFacade. That last one is a test-app-only change (Filament Shield's facade in the workbench demo), so it should not alter runtime behaviour for consumers. Treat the patch as safe; treat the 2.x line as the thing that needs evaluation.

Shield is now a first-class assumption in the test app. If you use Filament Shield for permissions, the settings page needs a permission defined for it or only super-admins will see it — which is usually the desired outcome, but it's silent when it isn't. Check AuthServiceProvider/policy wiring if the page mysteriously vanishes for a role you expected to have it.

Queued jobs and console commands are not covered. The plugin hooks the Filament panel request lifecycle. Exceptions thrown in queue workers, scheduled commands, and non-panel routes will only reach Sentry if sentry/sentry-laravel is configured independently. This is the single most common source of "Sentry is broken" reports after install.

Config caching bites. After publishing or editing the config, php artisan config:clear (or re-run config:cache in deploy). A stale cached config with an empty DSN looks identical to a broken install.

Debugging a silent integration. In order: (1) is SENTRY_LARAVEL_DSN actually set in the environment the app is running under, (2) does a manually thrown exception from a plain route reach Sentry — if not, the problem is sentry/sentry-laravel, not this package, (3) does the same exception from inside the panel reach Sentry — if not, the problem is this package's registration, (4) does the event have a user attached — if not, check the panel guard. Work that ladder in order; it isolates the fault to one layer every time.

Sampling is your quota lever. Once the panel is instrumented, admin panels generate a disproportionate share of exceptions (form validation edge cases, missing media, third-party API failures on a resource page). Set traces_sample_rate low and use Sentry's inbound filters aggressively before you discover this on an invoice.

Extension points. The plugin class exposes a fluent API for the common knobs; for anything it does not cover, publish the views and override, or bind your own implementation in a service provider. Prefer wrapping the plugin's registration over forking — a fork of a Filament plugin is a permanent maintenance tax that compounds at every Filament major.

Watch the issue tracker around majors. A 2.0→2.0.1 patch this soon after a major usually means the 2.x branch is still settling. Skim open issues for Filament v4 panel-registration or Shield-related breakage before committing your team to the upgrade.