Filament Notification Bell Laravel Package

Getting Started

Minimal Setup Steps

1. Installation

   composer require benriadh1/filament-notification-bell
   

   Publish assets and config:

   php artisan vendor:publish --provider="Benriadh1\FilamentNotificationBell\ServiceProvider" --tag="config"
   php artisan vendor:publish --provider="Benriadh1\FilamentNotificationBell\ServiceProvider" --tag="migrations"
   php artisan migrate
   

2. Configure Reverb/Pusher Add your Reverb/Pusher credentials to .env:

   BROADCAST_DRIVER=reverb
   REVERB_APP_ID=your_app_id
   REVERB_APP_KEY=your_app_key
   REVERB_APP_SECRET=your_app_secret
   

3. Register the Panel Add to app/Providers/Filament/AdminPanelProvider.php:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->id('admin')
           ->notificationBell();
   }
   

4. First Notification Test Use the notify() helper or Notification facade to trigger a test notification:

   use Illuminate\Support\Facades\Notification;
   Notification::route('filament-notification-bell', auth()->user())
       ->notify(new \App\Notifications\TestNotification);
   

Implementation Patterns

Core Workflow: Sending Notifications

1. Define Notification Class Extend FilamentNotification for bell-specific behavior:

   use Benriadh1\FilamentNotificationBell\Notifications\FilamentNotification;
   
   class TestNotification extends FilamentNotification
   {
       public function __construct(
           public string $title,
           public string $body,
           public string $url = null,
       ) {}
   }
   

2. Trigger Notifications

   // Via helper
   notify(new TestNotification('New Task', 'You have a new task assigned', route('tasks.show', 1)));
   
   // Via facade (with route)
   Notification::route('filament-notification-bell', auth()->user())
       ->notify(new TestNotification('Update', 'System update available'));
   

3. Batch Processing Use FilamentNotificationBell::markAsRead() to clear notifications:

   FilamentNotificationBell::markAsRead(auth()->user());
   

Panel Customization

1. Override Views Publish views first, then modify:

   php artisan vendor:publish --tag="filament-notification-bell-views"
   

   Customize resources/views/vendor/filament-notification-bell/...

2. Dynamic Styling Extend CSS via resources/css/filament-notification-bell.css:

   .filament-notification-bell {
       --bell-badge-bg: #ff0000;
   }
   

3. Panel Modes Configure in config/filament-notification-bell.php:

   'panel_mode' => 'dropdown', // or 'slide-over'
   

Real-Time Integration

1. Reverb Events Listen to filament-notification-bell channel:

   Reverb::channel('filament-notification-bell')
       ->listen(function (Notification $notification) {
           // Handle custom logic
       });
   

2. Fallback Polling Enable in config:

   'fallback_polling' => [
       'enabled' => true,
       'interval' => 30, // seconds
   ],
   

Gotchas and Tips

Common Pitfalls

1. WebSocket Disconnections

   • Issue: Notifications not updating due to dropped connections.
   • Fix: Enable polling fallback or implement Reverb reconnection logic:

     // resources/js/app.js
     window.Echo.connector.reconnect = () => {
         setTimeout(() => window.Echo.connector.connect(), 1000);
     };
     

2. Permission Denied

   • Issue: 403 Forbidden when sending notifications.
   • Fix: Ensure the user has the view-filament-notification-bell permission:

     Gate::define('view-filament-notification-bell', function ($user) {
         return $user->can('view-notifications');
     });
     

3. RTL Layout Issues

   • Issue: Bell panel misaligned in RTL languages.
   • Fix: Override the RTL CSS:

     .filament-notification-bell.rtl .bell-panel {
         right: auto;
         left: 0;
     }
     

4. Notification Duplication

   • Issue: Same notification appears multiple times.
   • Fix: Add a unique notification_id to your Notification class and implement deduplication in the handle() method.

Debugging Tips

1. Check Reverb Logs

   tail -f storage/logs/laravel.log | grep reverb
   

2. Verify WebSocket Connection Use browser DevTools → Network tab to check for WebSocket upgrades (ws:// or wss://).

3. Test Polling Fallback Disable WebSocket temporarily in config to test polling:

   'use_reverb' => false,
   

Extension Points

1. Custom Notification Types Add a type property to your FilamentNotification and style dynamically:

   class AlertNotification extends FilamentNotification {
       public function __construct(public string $type) {}
   }
   

   .filament-notification-bell .notification[type="alert"] {
       background: #ffebee;
   }
   

2. Database Schema Extend the notifications table via migration:

   Schema::table('notifications', function (Blueprint $table) {
       $table->string('custom_field')->nullable();
   });
   

3. Event Listeners Listen for NotificationSent events to log or process:

   Notification::sent(function ($notification, $channels) {
       if ($notification instanceof FilamentNotification) {
           // Custom logic
       }
   });
   

4. Dark Mode Overrides Force light/dark mode in config:

   'dark_mode' => 'auto', // auto, light, or dark
   

Performance Considerations

1. Batch Processing For high-volume notifications, batch inserts:

   DB::transaction(function () {
       Notification::send($user, $notifications);
   });
   

2. Lazy Loading Disable "Load more" pagination if notifications are static:

   'pagination' => [
       'enabled' => false,
   ],
   

3. WebSocket Throttling Limit Reverb events per second to avoid overload:

   'reverb' => [
       'throttle' => 10, // events/second
   ],