Filament Alerts Laravel Package

Getting Started

Install the package and run its installer:

composer require tomatophp/filament-alerts
php artisan filament-alerts:install

Register the plugin in your Filament panel provider:

->plugin(\TomatoPHP\FilamentAlerts\FilamentAlertsPlugin::make())

Add the notification trait to any model that should receive alerts, usually User:

use TomatoPHP\FilamentAlerts\Traits\InteractsWithNotifications;

class User extends Authenticatable
{
    use InteractsWithNotifications;
}

Start a queue worker, because delivery is queued:

php artisan queue:work

Look first at:

• config/filament-alerts.php after publishing config
• The Filament “Notification Templates” resource
• TomatoPHP\FilamentAlerts\Services\Drivers\* for built-in drivers
• The plugin class for hideNotificationsResources() and useSettingsHub()

Your first useful workflow is template-driven: create a notification template in the admin UI with a unique key, then send it from application code:

use TomatoPHP\FilamentAlerts\Facades\FilamentAlerts;

FilamentAlerts::notify($user)
    ->template($templateId)
    ->title(['{name}' => $user->name])
    ->body(['{name}' => $user->name])
    ->send();

Implementation Patterns

Use templates as the contract between admins and code. Let admins manage title/body/channel/type/action in Filament, while developers reference a stable template key or ID. Keep template keys unique and treat them like API identifiers.

Prefer the facade for application-triggered notifications:

FilamentAlerts::notify($user)
    ->template('order-shipped')
    ->title(['{order}' => $order->number])
    ->body(['{order}' => $order->number])
    ->send();

Use Filament’s native notification API when you want Filament-style actions and read state, but route delivery through a package driver:

use Filament\Notifications\Notification;
use TomatoPHP\FilamentAlerts\Services\Drivers\EmailDriver;

Notification::make()
    ->title('Invoice ready')
    ->body('Your invoice is available.')
    ->actions([
        \Filament\Notifications\Actions\Action::make('view')
            ->url($invoiceUrl)
            ->markAsRead(),
    ])
    ->sendUse($user, EmailDriver::class);

Use direct channel helpers for simple transactional messages where a template is overkill:

$user->notifyEmail('Your export is ready.', 'Export complete', $url);
$user->notifyDB('Your export is ready.', 'Export complete', $url);

Register custom drivers, types, actions, and user types in a service provider’s boot() method. Register them before any send path depends on them:

use TomatoPHP\FilamentAlerts\Facades\FilamentAlerts;
use TomatoPHP\FilamentAlerts\Services\Concerns\NotificationDriver;

FilamentAlerts::register(
    NotificationDriver::make('sms')
        ->label('SMS')
        ->color('primary')
        ->icon('heroicon-o-device-phone-mobile')
        ->driver(\App\Notifications\Drivers\SmsDriver::class)
);

For custom drivers, extend the package Driver class and implement setup() and sendIt(). Follow the built-in DatabaseDriver pattern: dispatch jobs rather than sending inline, and handle both a single modelId and a broadcast-to-all-models case.

Use the resource hooks to extend the admin UI without forking the package:

use TomatoPHP\FilamentAlerts\Filament\Resources\NotificationsTemplateResource\Table\NotificationsTemplateTable;

NotificationsTemplateTable::register([
    \Filament\Tables\Columns\TextColumn::make('internal_notes'),
]);

The same hook pattern exists for table actions, filters, bulk actions, forms, infolists, and page actions. If you need larger UI changes, override resource classes via the config file rather than editing vendor code.

Hide the package resources when notification templates should be developer-managed rather than admin-managed:

->plugin(
    \TomatoPHP\FilamentAlerts\FilamentAlertsPlugin::make()
        ->hideNotificationsResources()
)

Enable useSettingsHub() only if you want SMTP settings editable from the panel. Treat that as an operational feature, not a developer convenience.

Gotchas and Tips

• Queue delivery is mandatory. If notifications “send” but never arrive, check php artisan queue:work, failed jobs, and your queue connection before debugging templates.
• Template keys must be unique. Duplicate keys make sends ambiguous. Validate keys during template creation and avoid renaming keys after code references them.
• Template argument consistency matters. The README shows both IDs and keys in different places. Pick one convention, test it, and fall back to the other only if necessary.
• Replacement is literal, not Blade. title(['find-text' => 'replace']) replaces matching text. It is not a full templating engine. Keep placeholders explicit and validate required data before sending.
• sendUse() is not the same as send(). Filament’s normal send() bypasses package drivers and logs. Use sendUse($user, Driver::class) when you need package delivery behavior.
• The trait is required on recipients. Database notifications and direct helper methods depend on InteractsWithNotifications. Custom auth models may also need a registered notification user type.
• Register custom components early. Driver/type/action registrations belong in boot(). If config is cached, clear it after changes with php artisan config:clear.
• FCM and Discord are separate packages. The core package advertises FCM service worker support, but the actual FCM driver and service worker setup live in tomatophp/filament-fcm-driver. Budget time for public assets, service worker registration, and browser permission testing.
• SMTP settings via GUI can surprise ops. useSettingsHub() can override expected mail configuration. Restrict access, document ownership, and test against production config caching.
• Use logs for audit, not as proof of delivery. Notification logs are valuable for history and support, but still monitor driver-specific failures and queue exceptions.
• Migrations and assets may need verification after install. Confirm the installer published and ran migrations; publish config/views explicitly when you need to customize them:

php artisan vendor:publish --tag="filament-alerts-config"
php artisan vendor:publish --tag="filament-alerts-views"

• Pin and stage-test the package. It has low dependent usage and a very recent release. Pin a known version, test template sending, queue behavior, and resource hooks in staging before relying on it for critical notifications.