Notification Bell Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require caiquebispo/notification-bell
   

   Publish the package assets and config:

   php artisan vendor:publish --provider="CaiqueBispo\NotificationBell\NotificationBellServiceProvider" --tag="public"
   php artisan vendor:publish --provider="CaiqueBispo\NotificationBell\NotificationBellServiceProvider" --tag="config"
   

2. Run migrations:

   php artisan migrate
   

3. Add the trait to your User model:

   use CaiqueBispo\NotificationBell\Traits\HasNotifications;
   class User extends Authenticatable
   {
       use HasNotifications;
       // ...
   }
   

4. Include the Livewire component in your layout:

   @livewire('notification-bell::bell')
   

5. Trigger your first notification (e.g., in a controller):

   use CaiqueBispo\NotificationBell\Facades\NotificationBell;
   
   NotificationBell::success('Your notification title', 'Notification body content');
   

First Use Case: Displaying a Success Notification

// In a controller or service
NotificationBell::success('Profile Updated', 'Your profile has been successfully updated.');

• The notification will appear in the dropdown panel with a checkmark icon (Tailwind text-green-500).
• Works seamlessly with Livewire’s reactivity—no manual refresh needed.

Implementation Patterns

Core Workflows

1. Triggering Notifications

Use the NotificationBell facade or helper class in controllers/services:

// Basic types
NotificationBell::success('Title', 'Body');
NotificationBell::error('Title', 'Body');
NotificationBell::warning('Title', 'Body');
NotificationBell::info('Title', 'Body');

// With custom icon (Tailwind class)
NotificationBell::custom('Title', 'Body', 'fas fa-bell-slash');

// With actions (e.g., "View" button)
NotificationBell::success('Title', 'Body')
    ->action('View', route('notifications.show'), 'primary');

2. Livewire Integration

• The notification-bell::bell component auto-renders in your layout.
• Customize the dropdown position via config:

  'position' => 'top-right', // 'top-left', 'bottom-left', 'bottom-right'
  

• Disable auto-dismiss in config:

  'autoDismiss' => false,
  

3. Queue System

• Notifications are queued by default (uses Laravel’s queue system).
• Fire sync for testing/debugging:

  NotificationBell::success('Title', 'Body')->sync();
  

• Process queues manually:

  php artisan queue:work
  

4. User-Specific Notifications

• Notifications are scoped to the authenticated user via the HasNotifications trait.
• Fetch unread notifications in a Livewire component:

  public function getNotificationsProperty()
  {
      return auth()->user()->unreadNotifications;
  }
  

5. Dark Mode Support

• The package includes Tailwind dark mode classes (dark: variants).
• Override colors in your tailwind.config.js:

  module.exports = {
      darkMode: 'class',
      theme: {
          extend: {
              colors: {
                  bell: {
                      DEFAULT: '#3b82f6',
                      dark: '#60a5fa',
                  },
              },
          },
      },
  };
  

Advanced Patterns

Customizing the Bell Component

Extend the Livewire component by publishing and overriding views:

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

Modify:

• resources/views/vendor/notification-bell/bell.blade.php (main dropdown)
• resources/views/vendor/notification-bell/notification.blade.php (individual notification)

Adding Custom Notification Types

Create a helper method in app/Helpers/NotificationHelper.php:

use CaiqueBispo\NotificationBell\Facades\NotificationBell;

if (!function_exists('customNotification')) {
    function customNotification($title, $body, $icon = 'fas fa-robot')
    {
        return NotificationBell::custom($title, $body, $icon)
            ->priority('high')
            ->expiresNow();
    }
}

Bulk Actions

Use the NotificationBell facade to mark all as read:

NotificationBell::markAllAsRead();

Gotchas and Tips

Pitfalls

1. Queue Stuck Notifications:

   • If notifications aren’t appearing, check your queue worker (php artisan queue:work).
   • Debug: Temporarily disable queuing in config:

     'queue' => false,
     

2. Livewire Component Not Rendering:

   • Ensure the @livewire directive is in your layout after the <head> but before </body>.
   • Fix: Clear Livewire cache:

     php artisan livewire:discover
     

3. Dark Mode Conflicts:

   • If dark mode styles don’t apply, verify your layout includes:

     <html class="dark">
     

   • Override dark colors in your CSS:

     .dark .bell-notification {
         background-color: #334155;
     }
     

4. Notification Persistence:

   • Notifications are soft-deleted (not hard-deleted). To purge old ones:

     auth()->user()->notifications()->where('created_at', '<', now()->subDays(30))->forceDelete();
     

Debugging Tips

1. Log Queued Jobs: Add this to your AppServiceProvider:

   NotificationBell::setLogger(function ($message) {
       \Log::debug('NotificationBell: ' . $message);
   });
   

2. Inspect Database: Check the notifications table for stuck jobs:

   SELECT * FROM notifications WHERE read_at IS NULL LIMIT 10;
   

3. Disable Auto-Dismiss: Temporarily set 'autoDismiss' => false in config to debug visibility.

Extension Points

1. Custom Storage: Override the notification model by binding your own:

   NotificationBell::setNotificationModel(App\Models\CustomNotification::class);
   

2. Event Listeners: Listen for notification events (e.g., NotificationCreated):

   use CaiqueBispo\NotificationBell\Events\NotificationCreated;
   
   NotificationCreated::listen(function ($notification) {
       \Log::info('New notification created: ' . $notification->title);
   });
   

3. API Endpoints: Expose notifications via API using Laravel Sanctum/Passport:

   Route::middleware('auth:sanctum')->get('/notifications', [NotificationController::class, 'index']);
   

Pro Tips

• Batch Processing: Use NotificationBell::batch() to group related notifications:

  NotificationBell::batch('System Updates')
      ->add(NotificationBell::success('Update 1', 'Details...'))
      ->add(NotificationBell::warning('Update 2', 'Details...'));
  

• Localization: Override notification strings in config/notification-bell.php:

  'labels' => [
      'new_notifications' => 'You have __count__ new notifications',
  ],
  

• Performance: For high-traffic apps, preload notifications in Livewire:

  public function mount()
  {
      $this->notifications = auth()->user()->notifications()->latest()->take(50)->get();
  }