Filament Alert Box Laravel Package

Getting Started

This package adds a configurable alert box to Filament panels, with a Manage alerts page per panel and support for custom render hooks that can be used outside Filament entirely (e.g. a public Blade page).

1. Install and publish assets/config:

   composer require <vendor>/filament-alert-box
   php artisan vendor:publish --tag="filament-alert-box-config"
   php artisan vendor:publish --tag="filament-alert-box-migrations"
   php artisan migrate
   

2. Register the plugin in every panel that should have its own alerts:

   use FilamentAlertBox\AlertBoxPlugin;
   
   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugin(AlertBoxPlugin::make());
   }
   

3. Open the panel's Manage alerts page, create an alert, and confirm it renders in that panel.

Where to look first:

• config/filament-alert-box.php — especially custom_hooks, which controls the alerts rendered globally from non-panel views.
• AlertBoxPlugin — now only registers hooks scoped to the panel it was booted in.
• The Manage alerts page — the primary day-to-day surface for content editors.

First real use case: an admin panel alert for staff announcements, plus a custom hook rendered from your public site's layout for marketing banners.

Implementation Patterns

Treat panels as alert channels. Since 2.0.0, storage is keyed per panel (['admin' => [...], 'members' => [...]]). Design your panels deliberately: if admin and members share a plugin instance today, assume they are now isolated audiences. Duplicate intentionally, don't rely on the old shared behaviour.

Use custom hooks for anything outside a panel. Alerts registered through config('filament-alert-box.custom_hooks') are registered globally from the service provider and are intentionally not panel-scoped. This is the correct mechanism for:

// config/filament-alert-box.php
'custom_hooks' => [
    'filament-alert-box::public-banner',
],

{{-- resources/views/layouts/app.blade.php --}}
@include('filament-alert-box::public-banner')

Because they bypass the panel lifecycle, they will render on public pages even though no Filament panel booted — the fix called out in the changelog.

Run the migration as part of your deploy pipeline. For 2.0.0 upgrades:

# Preview first
php artisan filament-alert-box:migrate-alerts --dry-run

# CI/CD
php artisan filament-alert-box:migrate-alerts --all --no-interaction

Then have an editor open each panel's Manage alerts page and prune duplicates — the command copies, it never deletes. Do not run --all blindly if some panels are internal/staging-only.

Seed demos per panel in local/dev. AlertBoxSeeder now writes into every panel registering AlertBoxPlugin, using the new format. This is convenient for onboarding and tests, but it is a much broader write than before — never wire it into production seeding.

Use the helpers for upgrade and diagnostic code. AlertBox::isLegacyAlertsFormat() lets you assert state in tests or write one-off checks; AlertBox::isCustomHook() is useful when filtering a mixed alert collection (e.g. only panel-scoped alerts in a panel-specific widget).

Gotchas and Tips

• The silent auto-migration is the biggest trap. If you skip the command, the legacy shared list is duplicated into every registered panel the first time any panel saves the Manage alerts page. The edit is then applied only to that panel. Nothing is lost, but you lose the chance to choose which panels receive copies — run the command deliberately in staging first.
• --all means all registered panels, including panels you may have added for internal tooling. Review the dry-run output before running it unattended.
• Custom hooks are the exception to scoping. An alert created from a custom hook is global by design; it will appear wherever that hook renders, regardless of which panel's Manage alerts page was used to author it. Don't expect to target a custom-hook alert at a single panel.
• Plugin boot is now panel-local. AlertBoxPlugin::boot() only registers the current panel's hooks. Code that previously relied on the plugin registering all hooks during any panel boot (e.g. rendering an alert from a non-panel controller or a queued digest) should be migrated to a custom hook instead.
• Custom hook registration moved to the service provider. If custom hooks render stale or empty content, check php artisan config:cache — the hook list is read from config, so changes need a cache refresh.
• Verify the stored format after upgrading. The settings payload is now keyed by panel. Inspect it and use AlertBox::isLegacyAlertsFormat() to confirm the migration ran; legacy-shaped data will be re-duplicated the next time it is saved.
• Idempotency is not documented. Run --dry-run before re-running the command in an environment where it has already been executed; the release notes don't promise that a second run is a no-op.
• Seeder scope widened. AlertBoxSeeder now seeds every panel where the plugin is registered. Keep it behind local/testing guards.
• Upgrade checklist: publish and review config, run migrate-alerts --dry-run, run the real migration per environment, prune each panel, then smoke-test one public page (custom hook) and one panel page (scoped alert) to confirm both registration paths behave.