Filament Exceptions Laravel Package

Technical Evaluation

Architecture fit. bezhansalleh/filament-exceptions is a Filament panel plugin, not an observability service. It hooks Laravel's exception handler, persists throwables into an app-owned database table, and renders them as a Filament resource — list page with filters, a detail view with stack trace and request context, a resolve action, and an unresolved-count navigation badge. For a TPM the value is not better error data, it's a shorter path from "something broke" to "someone owns it," delivered inside a surface the team already opens daily. It fits when three conditions hold together: the product is Laravel + Filament v4, the people who triage already live in the panel (support, QA, ops, technical founder), and error volume is modest enough that an unpruned table stays unremarkable. It offers no alerting, no grouping intelligence beyond recurrence counts, no tracing, and no release-health correlation — it is a complement to Sentry/Flare/Bugsnag and cannot be positioned as incident detection without setting up a false expectation the team will discover at the worst moment.

The strategic leverage is workflow plus deferred spend. It converts an existing manual ritual — spreadsheet, Slack thread, "did anyone see this?" — into a filterable, resolvable inbox with a badge that answers "does anyone need to look at this right now?" Secondarily, if we ship Filament panels to clients or as agency handover, a built-in error inbox reads as operational maturity at roughly half a day of engineering. Both are legitimate TPM wins; neither is an APM replacement.

Integration feasibility. Well-bounded. Composer install, register the plugin on the target panel, publish config and migration, define a policy/gate, schedule pruning. No external service, no credentials, no Node build step, no vendor onboarding. Realistic effort is ~0.5 day for a single-panel app plus a compliance pass on what gets stored. The one structural commitment is version coupling: the 4.x line tracks Filament v4, so every Filament major becomes a coordinated two-package upgrade. That is a recurring, predictable calendar cost to communicate upward, not a surprise to absorb mid-sprint.

Technical risk. Ranked by the likelihood of it actually hurting us:

• Write-path safety is the release gate, not a nice-to-have. Capture runs inside the exception handler. If the database is unavailable or the table is missing, the worst case is masking the original exception or a recursive capture loop that turns a single failure into an outage. Validate explicitly in a sandbox by dropping the table. A package that fails closed here is disqualified regardless of how good the UI is.
• Capture latency under storms. Capture is on the request path. During an exception storm from a bad deploy, write amplification degrades the service that is already failing. Needs a measured answer, not an assumption.
• PII and data-residency exposure. Stack traces, request bodies, headers, cookies, and Authorization values routinely carry tokens, emails, and internal paths. Keeping them in the primary database expands our compliance surface — GDPR/DSAR response, backup scope, DB access control — and turns a tooling choice into a data-handling decision the PM owns, not an engineering default. Redaction and retention must be specified before launch, not retrofitted.
• Unbounded growth by default. Retention is ours to schedule. Stack traces are fat rows and growth is linear with error count. The list page and the navigation badge (a count query on every panel render) degrade as the table grows — a subtle, self-inflicted performance tax on the admin panel.
• Governance signals. MIT, ~200 stars, 0 dependents, single maintainer with a healthy Dependabot and CI posture. Low lock-in (drop plugin, drop table) makes it a cheap bet, but the thin dependent base and bus-factor-of-one should be logged as accepted risk with a re-evaluation trigger — not waved through.

Release 4.2.1 is a pure maintenance patch: Dependabot bumps (fetch-metadata 2.5.0→3.0.0→3.1.0, actions/checkout 6→7), a docs badge-link fix, and one behavioral change where getNavigationBadgeColor() now delegates to the plugin. Only teams that overrode badge color on the resource are affected; no migrations, no deprecations, no config removals, no action. That cadence is a mild positive for "safe to depend on" and should consume zero sprint capacity.

Key questions.

1. Does capture fail open on write failure, or can it mask or recurse on the original exception? (Blocks rollout.)
2. Is capture synchronous on the request path? What is the measured latency cost and behavior under a storm?
3. Is redaction of request bodies, headers, cookies, and Authorization supported in config, or do we own it via middleware/serializer?
4. Is there a first-class prune command we schedule, or does the package self-schedule? Who is alerted if pruning silently stops?
5. Which panels expose the viewer — production admin only, or staging too — and what gate restricts both list and view?
6. Multi-tenant: is scoping expected, or must we build it so admins don't see cross-tenant exceptions?
7. Does 4.x publish a Laravel/PHP/Filament support matrix and deprecation policy we can plan an upgrade calendar against?

Integration Approach

Stack fit. Laravel + Filament v4 with MySQL/Postgres and standard package conventions — service provider, publishable config and migrations, panel plugin registration. It slots into an existing panel with no new runtime dependency, no sidecar, no message queue. Outside Filament it delivers nothing, and inside Filament v3 or v5 it will not install cleanly; confirming the panel's Filament major is the first checkbox, not the last.

Migration path. Additive and reversible in both directions. Install, register on the target panel(s), publish config and migration, run one additive migration, define the policy gate, schedule pruning, ship. Rollback is dropping the plugin and then the table — which is why the exceptions table must be treated as app-owned and disposable, never as an audit or compliance record. If a stakeholder starts treating these rows as an incident history of record, that is a scope change requiring its own retention and integrity guarantees.

Compatibility. The version coupling is the real constraint: Filament major bumps become two-package upgrades for us, and the plugin's release timing is not on our schedule. Mitigate by pinning the plugin minor alongside the pinned Filament minor and validating in the upgrade runbook. PHP and Laravel support matrices should be captured at install time so the upgrade calendar has a factual anchor rather than a guess.

Sequencing. Ordered so the risky parts are validated before the visible parts ship:

1. Sandbox spike (half a day). Install in a throwaway panel, drop the table mid-capture, and confirm fail-open behavior. Measure capture latency. This is the go/no-go.
2. Data-handling decision. Decide and document what gets persisted: redaction rules for headers, cookies, Authorization, and request bodies; retention window; whether production only. Get sign-off before writing real data.
3. Access control. Define the permission/gate and enforce on both list and view. Decide the role set — likely engineering plus a support lead, not the full support org.
4. Prune job. Implement, schedule, monitor, alert on failure. A silently broken prune job becomes a database problem in weeks.
5. Production rollout. Register on the production admin panel only, announce the workflow to the triage audience, and name an owner for the inbox.
6. Re-evaluation trigger. Log the conditions that reopen the paid-APM decision: sustained error volume above an agreed threshold, the first revenue-impacting incident, or the first request for alerting or trend analysis.

Operational Impact

Maintenance. Low ongoing engineering, non-zero PM attention. Two recurring costs: the coupled Filament upgrade (predictable, twice-a-year-ish, needs calendar space) and the data lifecycle we own — pruning, redaction rules that stay current as the app evolves, and periodic review of what secrets end up in request bodies. The 4.2.1 release demonstrates the maintainer is keeping the lights on; it is not evidence of a support contract. Budget no vendor escalation path — the answer to a plugin bug is a fork or a patch.

Support. The inbox is only as useful as the escalation path behind it. A resolved/unresolved toggle with no named owner becomes a graveyard within a quarter, and the badge count becomes noise people learn to ignore. Define the ritual before launch: who checks unresolved daily, what SLA applies to a new exception, and how an exception converts into a ticket or a fix. Support leads and QA gain read/triage access here — that is a staffing and escalation-path decision, and it needs the permission gate to be safe, not just courteous.

Scaling. Two scaling axes, and only one is about traffic. Vertically: the table grows linearly with error count, the list page and badge count query slow with it, and the admin panel pays the tax on every page render. Mitigate with retention, an index review, and — if badge count becomes a problem — disabling the badge. Horizontally: this only ever sees errors from this Laravel application. Failures in workers, queues, cron, other services, or non-PHP components never arrive. Do not let the panel's completeness create the impression that everything is visible.

Failure modes. Enumerated for the runbook:

• Capture failure masking the original exception, or a recursive loop — the catastrophic case, gated at step 1.
• Latency amplification during a storm, where capture makes a bad deploy worse.
• Silent prune failure leading to table bloat and slow admin pages.
• Redaction drift — a new endpoint logs a token into a request body we now persist indefinitely; this is a compliance incident, not a bug.
• Access-control gap on the detail page where sensitive payloads render; the list page being gated does not mean the view is.
• Cross-tenant leakage if admins from one tenant see another's exceptions, since scoping is not provided.
• Maintainer abandonment — absorbable (MIT, small surface, drop-table exit) but should be logged, not assumed away.
• False confidence — the most expensive failure mode is organizational: someone says "it's in the exceptions panel, we're covered" in a meeting where the actual answer is that nobody was paged.

Ramp-up. Half a day for a Laravel developer familiar with Filament: install, register, migrate, gate, schedule. For the triage audience — support, QA, a technical PM — ramp-up is a short walkthrough of filter, detail, and resolve, plus the one thing they must internalize: this is not monitoring. Position it explicitly as an internal triage convenience layer that defers a monitoring subscription, with a documented trigger for revisiting that spend. Get that framing into the decision log at adoption time; it is the cheapest insurance against the entire adoption being judged a failure the first time an incident goes unalerted.