Filament Discord Driver Laravel Package

Getting Started

v5.0.0 is the Filament v5 / Laravel 12–13 line. Confirm your app is on Filament v5 before upgrading; if you are still on the Filament v4 line, stay on the package's v4 branch and pin ^4.0 so Composer does not pull v5. The v5 line requires tomatophp/filament-alerts:^5.0, so the alerts package must be upgraded in lockstep.

Minimal setup:

1. composer require tomatophp/filament-discord:"^5.0" (adjust the package name if you install it under a different name; the important part is the ^5.0 constraint).
2. Run php artisan filament:upgrade if you are coming from the v4 line.
3. Publish the package config and any settings-hub migration, then php artisan migrate.
4. Register the plugin in your panel provider:

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugin(DiscordPlugin::make());
}

5. Put DISCORD_ERROR_WEBHOOK=... in .env, run php artisan config:clear, and throw a test exception in staging to confirm delivery.

Look first at the package config file (the DISCORD_* keys), then at the Settings Hub page the package registers. The first real use case is the error webhook: get env-based delivery working, then optionally move the webhook into the Settings Hub UI for per-environment overrides without redeploying.

Implementation Patterns

Env as baseline, Settings Hub as override. The 5.0.0 behavior is: non-empty Settings Hub values win; empty/null values fall back to DISCORD_*. Keep .env populated in every environment as the safe default, and use the Settings Hub only for deliberate overrides. This gives you a rollback path: clear the DB value and you are back on env config.

Wire error reporting once, centrally. Prefer Laravel 12's bootstrap/app.php withExceptions() hook or the package's reporter rather than sprinkling try/catch blocks. If the package auto-registers an exception reporter, verify it is active in the environment you care about; if not, call the notifier explicitly from ->report().

Queue webhook delivery. Error reporting should never add latency to a failing request. Route delivery through a queue connection (or dispatch()->afterResponse() if the package does not expose a queue toggle) and make sure a worker is running in the environments where you expect alerts.

Register the plugin in one panel. Settings Hub values are global, but panel registration is per panel. Registering in multiple panels generally means duplicate notifications for the same event.

Use the Settings Hub for rotation, not for secrets hygiene. Rotating a compromised Discord webhook from the UI is the main operational win. Keep separate webhooks per environment/channel so staging noise never reaches the production channel.

Test with Http::fake(). Mirror the package's regression tests: assert the settings-hub value is used when present, and that the env value is used when the DB value is empty. This is exactly the behavior that changed in 5.0.0.

Fan out through filament-alerts. If you need Slack/email in addition to Discord, listen to the alerts events rather than duplicating exception-handler wiring.

Gotchas and Tips

The settings-hub fix can change production routing on upgrade. Before 5.0.0, error webhook values saved in the Settings Hub were silently ignored. After upgrading, any stale value someone saved earlier will suddenly take effect. Audit the settings row before deploying, or you may send production errors to an old test webhook.

Clearing a field does not disable the webhook. Empty Settings Hub values fall back to DISCORD_*. To truly disable delivery in an environment, use the package's enable flag or empty the env value there; do not rely on clearing the UI field.

Version pinning is the first upgrade trap. v5.0.0 is a breaking line (Filament v5, Laravel 12/13, filament-alerts ^5.0). Run composer why-not if the install fails, and keep the v4 branch for Filament v4 apps.

Config and settings caches. With config:cache in production, env changes require a redeploy. Settings Hub reads may also be cached; clear the relevant cache after changing values, otherwise you will debug a webhook that is actually correct.

Secrets live in the database now. If you use the Settings Hub, treat DB dumps and backups as secrets, and scrub the webhook before sharing dumps.

Discord limits. Webhooks are rate-limited and message content is capped (~2000 chars). Truncate stack traces or send them as a file attachment; dedupe or throttle repeated exceptions so one broken loop does not get your webhook rate-limited.

Some exceptions never reach you. Exceptions listed in dontReport (validation, auth, 404s by default) will not hit the reporter. Confirm your handler still reports what you expect after wiring the package.

Debug checklist when nothing arrives: Settings Hub value non-empty → env fallback present → queue worker running → webhook still valid in Discord (deleted webhooks return 404) → exception is not in dontReport → config cache cleared.

Extension points. If the default payload is not enough, bind a custom notifier/client in the service provider or listen to the filament-alerts events. Add a CI matrix entry for Laravel 12/13 + Filament v5; the package ships regression coverage for the env-fallback behavior, so your app tests should assert the same precedence.