Getting Started

Minimal Setup

Installation:

composer require tomatophp/filament-alerts

Publish the config file:

php artisan vendor:publish --provider="TomatoPHP\FilamentAlerts\FilamentAlertsServiceProvider" --tag="filament-alerts-config"

Configure Channels: Edit config/filament-alerts.php to define your notification channels (e.g., mail, database, fcm, filament). Example:

'channels' => [
    'mail' => [
        'enabled' => true,
        'from' => 'no-reply@example.com',
    ],
    'fcm' => [
        'enabled' => true,
        'api_key' => env('FCM_API_KEY'),
    ],
],

First Use Case: Send a notification via Filament’s native UI:

use TomatoPHP\FilamentAlerts\Facades\FilamentAlerts;

FilamentAlerts::send(
    user: $user,
    template: 'welcome', // Matches a template in `resources/views/vendor/filament-alerts/`
    data: ['name' => $user->name]
);

Define a Template: Create a Blade template at resources/views/vendor/filament-alerts/welcome.blade.php:
```
<h1>Welcome, {{ $data['name'] }}!</h1>
<p>You’ve successfully registered.</p>
```

Implementation Patterns

Core Workflows

Template-Based Notifications:
- Store reusable templates in resources/views/vendor/filament-alerts/ (e.g., order_confirmation.blade.php).
- Pass dynamic data via the data array:
```
FilamentAlerts::send($user, 'order_confirmation', ['order_id' => 123]);
```

Multi-Channel Dispatch:

Send to all enabled channels by default:

FilamentAlerts::send($user, 'template_name');

Target specific channels:

FilamentAlerts::send($user, 'template_name', [], ['channels' => ['mail', 'fcm']]);

Filament UI Integration:

Use the filament-alerts:send command in Filament actions/resources:

use TomatoPHP\FilamentAlerts\Actions\SendAlertAction;

public static function getActions(): array
{
    return [
        SendAlertAction::make('Notify User')
            ->template('welcome')
            ->data(['name' => 'John']),
    ];
}

FCM (Firebase) Notifications:

Configure the fcm channel in filament-alerts.php:

'fcm' => [
    'enabled' => true,
    'api_key' => env('FCM_SERVER_KEY'),
    'topic' => 'user_updates', // Optional: broadcast to a topic
],

Macros for Custom Logic: Extend Filament’s notification service with macros:

use TomatoPHP\FilamentAlerts\FilamentAlerts;

FilamentAlerts::extend(function ($notifier) {
    $notifier->macro('urgent', function ($user, $template, $data = []) {
        return $notifier->send($user, $template, array_merge($data, ['urgent' => true]));
    });
});

// Usage:
FilamentAlerts::urgent($user, 'alert', ['message' => 'Critical update!']);

Integration Tips

Laravel Notifications: Leverage existing Laravel notification classes for complex logic, then pass them to FilamentAlerts:

$notification = (new OrderShipped($order))->via(['mail']);
FilamentAlerts::send($user, 'order_shipped', [], ['notification' => $notification]);

Queue Delayed Notifications: Use Laravel queues to delay notifications:

FilamentAlerts::later(now()->addHours(1), function () use ($user) {
    FilamentAlerts::send($user, 'reminder', ['task' => 'Complete profile']);
});

Dynamic Templates: Fetch templates dynamically from a database or API:

$templateContent = Cache::get("template_{$templateName}");
FilamentAlerts::send($user, null, [], ['content' => $templateContent]);

Testing: Mock the FilamentAlerts facade in tests:

FilamentAlerts::shouldReceive('send')->once()->with($user, 'template', ['data']);

Gotchas and Tips

Pitfalls

Template Paths:
- Templates must be placed in resources/views/vendor/filament-alerts/ or they won’t be found.
- Debug missing templates with:
```
php artisan view:clear
```
FCM Configuration:
- Ensure your Firebase project has the Cloud Messaging API enabled.
- The service-worker.js must be registered in your frontend (check browser console for errors).
- Legacy Key Issue: If using FCM_SERVER_KEY, ensure it’s a Server Key (not a Legacy Key) in Firebase Console.
Channel Priority:
- Notifications sent via FilamentAlerts override Filament’s native notifications if both are configured for the same event.
- Explicitly disable Filament’s native notifications if conflicts arise:
```
'filament' => [
    'enabled' => false,
],
```
Data Binding:
- Blade templates only receive the data array passed to send(). Avoid relying on global variables or session data.
- Use array_merge to combine default and dynamic data:
```
FilamentAlerts::send($user, 'template', ['default' => 'value'], ['data' => ['override' => 'value']]);
```
Rate Limiting:
- FCM has message limits. Large payloads may fail silently.
- Log FCM responses to debug:
```
'fcm' => [
    'enabled' => true,
    'log_responses' => true, // Add this to config
],
```

Debugging

Check Logs: Enable debug mode in filament-alerts.php:
```
'debug' => env('APP_DEBUG', false),
```
Logs will appear in storage/logs/laravel.log.
FCM Debugging: Use the FCM DebugView to inspect sent messages.

Template Errors: Wrap template rendering in a try-catch to avoid crashes:

try {
    FilamentAlerts::send($user, 'template');
} catch (\Exception $e) {
    Log::error("Template error: " . $e->getMessage());
    // Fallback to a plain text notification
    $user->notify(new PlainTextNotification("Fallback message"));
}

Extension Points

Custom Channels: Extend the TomatoPHP\FilamentAlerts\Channels\Channel class to add new channels (e.g., Slack, SMS):

namespace App\Notifications\Channels;

use TomatoPHP\FilamentAlerts\Channels\Channel;

class SlackChannel extends Channel
{
    public function send($notifiable, $template, $data)
    {
        // Custom logic to send to Slack
    }
}

'channels' => [
    'slack' => [
        'enabled' => true,
        'class' => \App\Notifications\Channels\SlackChannel::class,
    ],
],

Template Preprocessing: Add a macro to preprocess template data:

FilamentAlerts::extend(function ($notifier) {
    $notifier->macro('preprocess', function ($user, $template, $data = []) {
        $data['processed_at'] = now()->format('Y-m-d H:i');
        return $notifier->send($user, $template, $data);
    });
});

Event Listeners: Trigger notifications from Laravel events:

use TomatoPHP\FilamentAlerts\Facades\FilamentAlerts;

event(new UserRegistered($user));
FilamentAlerts::send($user, 'welcome');

Filament Policy Integration: Restrict who can send alerts via Filament policies:
```
public static function canAccess(): bool
{
    return auth()->
```

Filament Alerts Laravel Package