Filament Discord Driver Laravel Package

Technical Evaluation

Architecture fit This is a thin Filament plugin that binds Discord webhook delivery into the Tomatophp settings-hub configuration surface, with DISCORD_* environment variables as the fallback configuration source. Architecturally it is low-coupling: it does not own persistence beyond settings-hub keys, does not introduce a queue or transport of its own, and sits at the edge of the application as an outbound notification adapter. That is a good fit for teams already standardising on the Tomatophp Filament stack, and a poor fit for anyone not already running filament-alerts and the settings hub, since v5.0.0 hard-requires tomatophp/filament-alerts ^5.0.

Integration feasibility Feasible but gated. The v5.0.0 line requires Filament v5 and supports Laravel 12 / 13; teams on Filament v4 must remain on the v4 branch, which is now a separate maintenance line. The release is primarily a compatibility and correctness release rather than a feature release — two config-resolution bugs are fixed and a CI matrix plus regression tests are added. The test and CI additions materially improve our confidence relative to the prior state, where we have no assessment on record and an empty evidence base.

Technical risk The dominant risk is version-lock coupling to two Filament majors plus a transitive Tomatophp dependency, all of which must move together. Secondary risks are behavioural: both fixes change effective configuration at runtime.

• Error-level webhook settings from the settings hub were previously ignored; after upgrade, error traffic will begin routing to the error channel. Teams that configured an error webhook and quietly relied on it being ignored will see alert destinations change.
• DISCORD_* env values are now retained when settings-hub values are empty, reversing the previous precedence outcome for partially-configured installs. Neither is a data-migration risk, but both are "works differently the moment you deploy" risks that must be validated in a non-production environment.

Key questions

• Is there a documented upgrade guide from the v4 line, and are settings-hub keys, config keys, and env variable names unchanged between majors?
• What is the support window and patching commitment for the v4 branch, given the maintainer has explicitly forked the maintenance line?
• Is Laravel 13 generally available, or is the CI matrix testing against an unreleased branch? This affects whether we can claim production support.
• Does the error-webhook fix change which channel receives exceptions by default when no error webhook is configured, or only when one is?
• Are webhook sends queued or synchronous, and do they implement retry/backoff against Discord rate limits?

Integration Approach

Stack fit Requires Filament v5, Laravel 12 or 13, tomatophp/filament-alerts ^5.0, and presumably the settings hub. Confirm the settings-hub version constraint alongside filament-alerts, since the fixes in this release are only meaningful if the hub is present and correctly versioned. Teams not on the settings hub can still operate via DISCORD_* env variables, and this release makes that path more robust — that is the lower-risk adoption mode if we want the alerting without the admin-UI configuration surface.

Migration path Adopt as a lockstep Filament major upgrade, not as an isolated package bump. Order: (1) upgrade Filament to v5 and Laravel to 12/13 on a branch; (2) upgrade filament-alerts to ^5.0; (3) upgrade this package to v5.0.0; (4) migrate settings-hub values and verify key parity; (5) exercise the env-fallback path explicitly. If the Filament v5 upgrade is not funded this cycle, pin to the v4 branch and record that as a tracked exception with a revisit date, because the v4 line is now a separate branch with an unclear longevity commitment.

Compatibility Highest-risk surface is config precedence. Test four states in staging: settings-hub values populated, settings-hub values empty with env populated, both populated (hub should win), and neither populated. Re-test after php artisan config:cache, since env-fallback logic is a common casualty of config caching.

Sequencing Do not deploy this in the same window as unrelated Filament or logging changes — the error-channel rerouting needs a clean observation window so we can attribute any change in alert destinations to this release. Ship to a staging environment with a dedicated test Discord webhook first, verify both the default and error channels receive the correct traffic, then promote.

Operational Impact

Maintenance Two maintained branches (v5 for Filament v5, v4 for Filament v4) means two upgrade paths and an eventual forced migration. Budget a recurring review of the v4 branch for security fixes, and set a deprecation checkpoint for the v4 line rather than letting it drift. The added regression tests and CI matrix reduce per-release verification cost, which offsets some of the dual-branch overhead.

Support Small-maintainer OSS package; support is GitHub-issue-based with no vendor SLA. Mitigate by keeping webhook configuration reproducible from code/env so a package regression can be worked around by dropping to env-only configuration. Note that the two bugs fixed here were both configuration-resolution defects that presumably shipped silently — assume similar defects are possible and monitor delivered alert volume rather than trusting configuration alone.

Scaling Alert volume scales with exception/notification rate, not user traffic. Outbound webhook delivery to Discord is subject to per-webhook rate limits; confirm whether sends are queued. If synchronous, an incident storm will generate blocking HTTP calls inside the request or exception path — a real availability concern. Recommend wrapping in a queue with retry/backoff if not already supported, and confirm behaviour when Discord is unreachable or returns 429.

Failure modes

• Silent misconfiguration: settings-hub values present but not applied (the exact class of bug fixed here) — alerts route to the wrong channel with no error.
• Precedence inversion after upgrade: env fallback now wins where it previously lost, changing destinations on partially-configured installs.
• Error-channel rerouting: previously-ignored error webhooks now take effect, potentially flooding a channel or, conversely, moving critical alerts away from the channel responders watch.
• Version-lock breakage: a Filament or filament-alerts minor bump ahead of this package's constraint blocks deployment.
• Webhook delivery failure with no fallback channel — alerting must not be the only path for critical errors.

Ramp-up Low engineering ramp-up (config-only integration, no schema of its own), but non-trivial verification ramp-up: four configuration states, two branch lines, and a required staging webhook to validate routing. Estimate half a day of engineer time for the v5 path if Filament is already upgraded, and treat the v4 pin as a separate migration work item with its own estimate.