Filament Alert Box Laravel Package

Getting Started

1. Install the package. It's a Filament panel plugin, so it belongs in the same composer require step as your other small Filament extensions:

   composer require rifrocket/filament-alert-box
   

   The project has a published config, so run the publish step next:

   php artisan vendor:publish --tag="filament-alert-box-config"
   

   If the tag isn't recognised, run php artisan vendor:publish and pick the package interactively — some single-maintainer Filament plugins name the tag differently than the README suggests.

2. Register the plugin on the panel(s) you want alerts on. In app/Providers/Filament/AdminPanelProvider.php:

   ->plugins([
       \Rifrocket\FilamentAlertBox\FilamentAlertBoxPlugin::make(),
   ])
   

   Because it's a panel plugin, alerts render only on panels where you register it. That's usually what you want — you rarely want a warning banner bleeding into a customer-facing panel.

3. Read these first, in this order:

   • The published config (config/filament-alert-box.php) — it tells you more about the alert schema (severity, dismissible, persistence key) than the README does.
   • The src/ directory, specifically anything that looks like a fluent builder (AlertBox, Alert, Concerns/...). The package advertises a "fluent API", and the class that exposes info(), success(), warning(), danger() is the surface you'll live in day-to-day.
   • The README.md examples — for a 4-star package, treat the README as the contract and the code as the source of truth. If they disagree, trust the code.

4. First use case: a single dismissible maintenance banner. Don't start with user-specific or dynamic alerts. Start by hard-coding one static banner in a service provider, confirm it renders in the panel layout, confirm the dismiss button persists across a page reload, then iterate. That's a 10-minute exercise that validates the whole integration.

Implementation Patterns

Static global alerts registered from a service provider

The cleanest place for site-wide notices (maintenance windows, policy updates, onboarding nudges) is a service provider's boot() — the alert is registered once per request, independent of any specific page:

public function boot(): void
{
    FilamentAlertBox::make()
        ->warning()
        ->message('Scheduled maintenance Sunday 02:00–04:00 UTC.')
        ->dismissible();
}

Use this pattern for anything that is genuinely the same for every user.

Per-page / per-resource alerts

When the alert is contextual — a draft notice on an edit page, an unsaved-changes warning — register it from the page class (mount(), getHeaderWidgets(), or a lifecycle hook) rather than globally. This keeps the alert lifetime tied to the page it belongs to and avoids leaking it into other admin surfaces.

Severity as the primary axis

Treat the four severities (info, success, warning, danger) as a closed enum in your own code. Wrap package calls in a single helper (e.g. app/Support/AdminAlerts.php) that exposes maintenance(), policyUpdate(), onboardingTip() etc. When the package API changes or you swap it out, you edit one file instead of grepping for ->warning() across ten pages.

Dismissibility and persistence

Dismissible alerts are only useful if the dismissal sticks for the right scope. Two rules of thumb:

• Per-user-per-alert for anything tied to a person (onboarding tips, "you haven't completed setup"). Use a stable, explicit key in the alert — ideally derived from a config constant, not a magic string.
• Session-only for ephemeral state (a form was saved). Don't persist this or users will come back next week to a stale "saved" banner.

The description calls out "optional persistence per user session" — so the persistence layer likely keys on the user session. This means impersonation and session regeneration will reset dismissals, which is usually fine but worth knowing.

Icon sizing (1.2.0)

The 1.2.0 release adds the ability to change the icon size on alerts. Use this to align alert icons with your panel's density — Filament panels tend to run either default or slightly tighter density, and the icon size is the most visible artefact of a mismatch. Add a single ->iconSize(...) (or equivalent) call in your wrapper helper rather than at every call site.

Integration with your existing Filament theme

The package uses Filament's design system, so danger will match text-danger-600 etc. If you have a custom theme (php artisan filament:theme), the alerts should inherit your overrides automatically. If they don't, the package is likely using its own CSS class names — check the published views and consider overriding them via a ->registerRenderHook() or a Blade view override in resources/views/vendor/filament-alert-box/.

Testing pattern

Because it's a panel plugin, the natural place to test it is a Filament test using Livewire::test(). If you're asserting alert presence on a page, assert on the message text, not on the CSS class or DOM structure — the latter is an implementation detail of the package and will break on minor upgrades.

Gotchas and Tips

The README and the release notes disagree

The description talks about a "dismissible alert banner" package; the 1.2.0 release note talks only about "changes size of icon". These are consistent — the icon is the alert's leading icon — but the release note is terse to the point of being unhelpful. Read the diff for 1.2.0 (git diff 1.1.x..1.2.0 on GitHub) before you depend on the new sizing API. The changelog's grammar ("functionality to changes size") does not inspire confidence that sizing shipped as a first-class, documented API.

Dismissal state is not free

Every non-dismissible alert costs zero bytes; every dismissible alert costs a write somewhere (session, cookie, or a per-user store). If you have a loop that registers alerts, guard it — registering ten dismissible alerts from a foreach will silently multiply the storage writes and can flood a session payload.

Alert key collisions

If your persistence is keyed per alert and you register two alerts with the same (or missing) key, dismissing one will dismiss the other. Always set an explicit key in any wrapper helper.

Plugin is panel-scoped

Forgetting to add the plugin to a second panel (e.g. a Support panel alongside Admin) is a common source of "the alert doesn't show up" bug reports. If an alert should appear everywhere, register the plugin on every panel — there is no global escape hatch.

View cache

After registering the plugin or changing the config, run:

php artisan filament:optimize-clear
# or, if that fails
php artisan view:clear && php artisan config:clear

Filament's panel discovery and Blade caching interact in ways that make package changes appear to have "no effect" until cleared. This is the #1 source of false bug reports in a Filament codebase.

Version pinning

For a 4-star, single-maintainer package, pin the minor version in composer.json ("rifrocket/filament-alert-box": "^1.2"), not just the major. The 1.2.0 change is additive, but the project's release cadence is sparse enough that a surprise breaking change in 1.3.0 would be a bad discovery during a framework upgrade.

Accessibility is on you

Alerts need role="status" (or role="alert" for danger) and aria-live="polite" on the container. If the package's Blade view doesn't include these, either override the view or wrap the alerts in your own live region. Sizing an icon without semantic control is half a solution — verify before you promise it to a design system.

Where to extend

Realistic extension points, in order of preference:

1. A wrapper helper in your app (app/Support/AdminAlerts.php) — always do this first.
2. Publishing and overriding the Blade view — for markup, roles, and class changes.
3. A custom render hook in the panel provider — for injecting alerts at a specific layout slot.
4. Forking — last resort, but realistic for a package this small. The surface area is probably under a few hundred lines.

Debugging checklist

When an alert doesn't appear:

• Is the plugin registered on this panel? (->getPlugins() on the panel)
• Did you clear the view and config caches?
• Is the alert being registered after the render hook fires? (Boot order matters — app->booted() vs provider boot().)
• Is the alert dismissible with a key that's already dismissed in this user's session? Clear the session or use an incognito window.
• Is there a danger-level alert being swallowed by a more restrictive panel theme? Check the actual HTML in the browser.