Filament Notifier Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require usamamuneerchaudhary/filament-notifier
   

   Publish the config and migrations:

   php artisan vendor:publish --provider="UsamaMuneerChaudhary\FilamentNotifier\FilamentNotifierServiceProvider" --tag="config"
   php artisan migrate
   

2. First Use Case: Sending a Basic Email Notification Register the notifier in your AppServiceProvider:

   use UsamaMuneerChaudhary\FilamentNotifier\Facades\FilamentNotifier;
   
   public function boot()
   {
       FilamentNotifier::channel('email')->using(\Illuminate\Mail\Mailer::class);
   }
   

   Trigger a notification in a Filament action or resource:

   use UsamaMuneerChaudhary\FilamentNotifier\Notifications\Notification;
   
   public static function getNotifications(): array
   {
       return [
           Notification::make()
               ->title('Welcome!')
               ->content('Thank you for signing up.')
               ->channel('email')
               ->to('user@example.com'),
       ];
   }
   

3. Where to Look First

   • Config File: config/filament-notifier.php (channels, templates, defaults).
   • Migrations: database/migrations/..._create_notifications_table.php (customize if needed).
   • Facade: FilamentNotifier (core API for sending, managing, and querying notifications).
   • Example Notifications: vendor/usamamuneerchaudhary/filament-notifier/src/Notifications/ (extend or replicate).

Implementation Patterns

Core Workflows

1. Multi-Channel Notifications Define channels in config/filament-notifier.php:

   'channels' => [
       'email' => [
           'driver' => \Illuminate\Mail\Mailer::class,
           'config' => [
               'from' => 'no-reply@example.com',
           ],
       ],
       'slack' => [
           'driver' => \UsamaMuneerChaudhary\FilamentNotifier\Channels\SlackChannel::class,
           'config' => [
               'webhook_url' => env('SLACK_WEBHOOK_URL'),
           ],
       ],
   ],
   

   Use in code:

   FilamentNotifier::send(
       Notification::make()
           ->channel(['email', 'slack'])
           ->to('user@example.com')
   );
   

2. Template Management Create reusable templates in resources/views/vendor/filament-notifier/email/welcome.blade.php:

   <h1>{{ $notification->title }}</h1>
   <p>{{ $notification->content }}</p>
   

   Reference them in notifications:

   Notification::make()
       ->template('email.welcome')
       ->data(['custom_var' => 'value'])
   

3. Scheduling Notifications Delay delivery via Laravel’s scheduler:

   Notification::make()
       ->delay(now()->addMinutes(30))
       ->channel('email')
   

   Process scheduled notifications via a command:

   php artisan filament-notifier:process
   

4. Filament Integration Display notifications in a Filament resource/page:

   use UsamaMuneerChaudhary\FilamentNotifier\Widgets\NotificationsWidget;
   
   public function getWidgets(): array
   {
       return [
           NotificationsWidget::make(),
       ];
   }
   

5. Event-Driven Triggers Listen for model events and auto-send notifications:

   use UsamaMuneerChaudhary\FilamentNotifier\Events\NotificationSent;
   
   public function registered(User $user)
   {
       FilamentNotifier::send(
           Notification::make()
               ->title('Account Created')
               ->content('Your account is ready!')
               ->to($user->email)
       );
   }
   

Integration Tips

• Laravel Queues: Configure config/filament-notifier.php to use queues for async processing:

  'queue' => [
      'enabled' => true,
      'connection' => 'redis',
  ],
  

• Custom Channels: Extend UsamaMuneerChaudhary\FilamentNotifier\Contracts\Channel:

  class CustomChannel implements Channel
  {
      public function send($notifiable, Notification $notification)
      {
          // Custom logic (e.g., SMS, Push)
      }
  }
  

  Register it in config/filament-notifier.php:

  'channels' => [
      'custom' => [
          'driver' => \App\Channels\CustomChannel::class,
      ],
  ],
  

• Testing: Use the FilamentNotifier facade in tests:

  $this->assertDatabaseHas('notifications', [
      'channel' => 'email',
      'to' => 'user@example.com',
  ]);
  

Gotchas and Tips

Pitfalls

1. Channel Configuration

   • Issue: Forgetting to bind channels to a driver (e.g., using() not set in AppServiceProvider).
   • Fix: Ensure all channels in config/filament-notifier.php have a driver key pointing to a valid class.
   • Debug: Check storage/logs/laravel.log for Channel [channel] is not configured errors.

2. Template Paths

   • Issue: Templates not found if placed outside resources/views/vendor/filament-notifier/.
   • Fix: Use the correct namespace in Notification::make()->template('path.to.template').

3. Queue Stuck Jobs

   • Issue: Scheduled notifications not processing due to queue worker issues.
   • Fix: Monitor queues with php artisan queue:work and ensure the filament-notifier:process command is scheduled in app/Console/Kernel.php:

     $schedule->command('filament-notifier:process')->everyFiveMinutes();
     

4. Recipient Validation

   • Issue: Not validating to recipients (e.g., email format) before sending.
   • Fix: Add validation in your notification logic:

     if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
         throw new \InvalidArgumentException('Invalid email address.');
     }
     

Debugging

• Log Notifications: Enable debug mode in config/filament-notifier.php:

  'debug' => env('APP_DEBUG', false),
  

  Logs will appear in storage/logs/filament-notifier.log.

• Inspect Queued Jobs:

  php artisan queue:list
  php artisan queue:failed-table
  

• Test Locally: Use the filament-notifier:test command to simulate sending:

  php artisan filament-notifier:test --channel=email --to=user@example.com
  

Extension Points

1. Custom Notifiable Models Extend UsamaMuneerChaudhary\FilamentNotifier\Contracts\Notifiable:

   class User implements Notifiable
   {
       public function routeNotificationFor($channel)
       {
           return $channel === 'email' ? $this->email : null;
       }
   }
   

2. Dynamic Templates Use Blade components for dynamic content:

   @component('filament-notifier::email.template')
       @slot('title') {{ $notification->title }} @endslot
       @slot('content') {{ $notification->content }} @endslot
   @endcomponent
   

3. Webhook Channels For external APIs (e.g., Twilio, SendGrid), create a channel:

   class WebhookChannel implements Channel
   {
       public function send($notifiable, Notification $notification)
       {
           Http::post(env('WEBHOOK_URL'), $notification->toArray());
       }
   }
   

4. Notification Actions Attach clickable actions to notifications:

   Notification::make()
       ->action('View Profile', route('profile.show'))
       ->channel('email')
   

Config Quirks

• Default Channel: Set a fallback channel in config:

  'defaults' => [
      'channel' => 'email',
  ],
  

• Rate Limiting: Configure in config/filament-notifier.php:

  'rate_limiting' => [
      'enabled' => true,
      'max_attempts' => 3,
      'decay_minutes' => 1,
  ],
  

• Environment-Specific Channels: Use .env variables:

  'channels' => [
      'slack' => [
          'webhook_url' => env('SLACK_WEBHOOK_URL'),
      ],
  ],