Filament Alerts Laravel Package

Technical Evaluation

Architecture fit. tomatophp/filament-alerts is a Filament-panel plugin, not a general Laravel notification package. It installs as a service provider + facade (FilamentAlerts), registers a panel plugin (FilamentAlertsPlugin::make()), and expects consuming models to adopt an InteractsWithNotifications trait alongside Laravel's Notifiable. Internally it is a thin orchestration layer over an abstract Driver class with concrete DatabaseDriver, EmailDriver, and pluggable Discord/FCM drivers, fronted by two Eloquent resources (templates and delivery logs) and backed by queue jobs (NotifyDatabaseJob, etc.). That is a sound, conventional shape for a Filament add-on and it fits cleanly if — and only if — our admin surface is Filament-first and our delivery needs are modest. It is a poor fit for an API-first or headless product where the operator UI is incidental.

Integration feasibility. Ceremony is low: composer require, a one-shot filament-alerts:install command, one plugin line in the panel provider, one trait on User, and a queue worker. That is roughly a half-day to first send. The package is unusually generous with extension seams for its size: custom drivers, types, actions, and user types register through the facade; resource tables/forms/infolists/actions expose static register() hooks; and every resource class is swappable via config. Crucially, those hooks mean we can customize without forking, which materially reduces the maintenance exposure that a 83-star, 0-dependent package would otherwise imply. The hideNotificationsResources() toggle also lets us consume the delivery engine while keeping our own UI, which is the integration mode I would favor.

Technical risk. The risks are concentrated in coupling and in what the package does not do:

• Filament major-version lock. The README references Filament\Tables\Actions\* and Filament\Infolists\*, which are Filament v3 namespaces; Filament v4 relocated actions to Filament\Actions. This is the single largest risk — a Filament major upgrade becomes a blocking dependency, not an incremental task.
• Vendor-class monkey-patching. The sendUse() macro is attached to Filament\Notifications\Notification, a vendor class. Any macro-name collision or upstream refactor of that class breaks delivery silently at runtime, not at install time.
• Static registry bootstrapping. Drivers/types/actions register via facade calls in boot(). That ordering interacts badly with config caching, package discovery, and test bootstrapping; registrations can vanish in a console or test context without an obvious failure.
• Primitive templating. Titles and bodies are string-replaced via ["find" => "replace"] arrays. There is no Blade rendering, no escaping contract, no localization/translation variants, no conditional blocks, and no template versioning — so an in-flight template edit changes the content of notifications already queued.
• Unbounded fan-out. The reference driver dispatches one job per record and, with no modelId, iterates $model::all(). On a real user table this is a memory and queue-flood hazard with no chunking, throttling, or batching in evidence.
• Secrets in the database. The optional settings hub writes SMTP credentials from the GUI. That is convenient for ops and a privilege-escalation target for anyone who reaches the admin panel, and it fights php artisan config:cache.
• Missing production primitives. No stated per-user channel preferences or opt-out, no rate limiting, no log retention/pruning command, no documented multi-tenancy scoping, and no idempotency key on queued sends (retries risk duplicate delivery).
• Bus factor. Single-vendor, 83 stars, 0 dependents, community-only support. CI, Dependabot, and code-style workflows are present and the release metadata looks active, so hygiene signals are better than the adoption signals.

TPM verdict: viable as a UI and delivery-log accelerator behind our own abstraction, not as a system of record. Treat the low composite score as "spike before commit," not "reject."

Key questions for the maintainer / spike:

1. Exact composer.json constraints — PHP, Laravel, and Filament (^3.x only)?
2. Is Filament v4 support on the roadmap, and does a v4 branch exist?
3. Is sendUse() guarded against macro collision, and is it registered idempotently?
4. Are template and log models tenant-scoped, or do they need a scoping patch?
5. Is there an idempotency/dedup key on the queued jobs, and how do retries behave?
6. How is the Notification object serialized into the job payload, and is it stable across Filament patch releases?
7. Is there a pruning/retention command for the logs table?
8. Can templates be seeded/registered programmatically (the README's "Register Notification Templates" checkbox is unchecked)?
9. What is the escaping behavior for template body HTML in the email driver?
10. Are Filament policies/permissions expected (Shield), or are the resources unguarded by default?

Integration Approach

Stack fit. This assumes Laravel 10/11/12-class runtime, a Filament v3 panel, a relational database, and a working queue (Redis preferred; database acceptable for pilot volumes). Email requires a transport; FCM requires HTTPS service-worker registration and device-token storage, which is a separate front-end workstream — plan for it explicitly rather than treating it as a driver config toggle.

Migration path. Two scenarios:

• Greenfield (we have no outbound notification system): adopt directly, but still behind an interface. Define App\Contracts\NotificationDispatcher with send(TemplateKey $key, Notifiable $recipient, array $vars) and implement it over FilamentAlerts::notify(). Package classes never appear in domain code.
• Consolidation (we already use Laravel Notifiable + Mail): do not migrate existing flows in the first phase. Run the package in parallel for new flows only, with the logs table as the comparison surface. Migrating live transactional email onto a package with an unversioned template model is a backward step unless the template builder is the actual requirement.

Compatibility. Build a short matrix before committing: Filament version (hard pin), Laravel version, PHP version, DB engine (MySQL vs Postgres for JSON/data columns), queue driver, mail transport, and FCM SDK version. Pin the package to an exact tag; use cweagans/composer-patches rather than a fork for small fixes, and only fork if a Filament v4 migration becomes necessary.

Build-vs-buy calibration. Laravel Notifiable + a notifications table + a modest Filament resource delivers roughly 60–70% of this in about two weeks of engineering — minus the visual template builder, the delivery log UI, and FCM. That is the real value being purchased. Frame the decision as "two weeks of build avoided for one vendor dependency assumed," and make it explicit.

Sequencing:

1. Spike (3–5 days). Scratch branch, install, send database + email + FCM to an internal test user, verify composer constraints, confirm no macro collision, measure query count and job fan-out on a 10k-user fixture. Written go/no-go.
2. Abstraction layer + template inventory. Ship the dispatcher interface, enumerate template keys as an enum, seed templates in code so keys are reproducible across environments.
3. Pilot one flow. Internal/staff-facing operational alerts only — lowest blast radius, exercises logs and queue.
4. Harden, then expand. Add log retention, queue-failure alerting, resource permission policies, and escaping review before any customer-facing email or push.
5. Scale out to customer flows once channel preferences/opt-out are implemented outside the package.

Operational Impact

Maintenance. Assume we own the upgrade path, not the vendor. Budget recurring effort each Filament major (namespace churn) and each Laravel major (queue/serialization changes). The abstraction layer is the mitigation that keeps a future rip-and-replace to days rather than quarters. Track the upstream repo for Filament v4 activity; if none appears within our upgrade window, plan the fork.

Support. Community-only: GitHub issues, no SLA, small community means low-probability long-tail answers. We need an internal runbook covering install, template key registry, driver registration, queue recovery, and log pruning. The hook-based customization means the runbook is short — but it must exist before the second engineer touches it.

Scaling. Three distinct bottlenecks:

• Queue throughput — one job per recipient; a 50k-recipient blast is 50k jobs. Size workers against peak campaign volume, not steady state.
• Log table growth — per-delivery rows with PII-adjacent content; without retention this becomes a multi-million-row table inside a year.
• FCM token lifecycle — invalid/rotated tokens must be pruned or every campaign accumulates failures and burns provider quota.

Cap any single send with an explicit chunked dispatcher in our wrapper; never call the package's no-modelId path against a production user table.

Failure modes (ranked by likelihood × impact):

Observability. Build a per-driver success/failure dashboard directly off the logs table on day one — it is the package's best feature and the cheapest operational control we get. Also alert on failed_jobs volume and queue age.

Security & compliance. Three items gate customer-facing rollout: (1) Filament policies on both resources — the sender UI is effectively a broadcast tool, so access is privileged; (2) SMTP credentials in the database are an admin-compromise vector, so prefer env-based transport and use the settings hub only in development; (3) notification logs contain message content and recipient identifiers, which makes them in-scope for GDPR retention limits — implement pruning with a documented window before the first customer send. No unsubscribe/opt-out mechanism is provided and none should be assumed; that is ours to build.

Ramp-up. A Filament-fluent developer reaches productive use in under a day; the driver/type/action registry and the static resource hooks are discoverable and follow Filament idioms. The non-obvious costs are the config-driven resource class overrides and the boot-order sensitivity of the registries — both belong in onboarding docs. Estimate one to two sprints from spike to hardened production for a single engineer, plus a front-end allocation if FCM is in scope.