Notifications Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation:

   composer require moox/notifications
   php artisan mooxnotifications:install
   

   • This runs migrations and publishes config/assets by default.

2. First Use Case:

   • Send a basic notification to a user:

     use Moox\Notifications\Notification;
     use Moox\Notifications\Channels\EmailChannel;
     
     $notification = new Notification('Welcome!');
     $notification->to(new EmailChannel('user@example.com'))
                  ->setContent('Welcome to our platform!');
     
     $notification->send();
     

3. Where to Look First:

   • Config: config/notifications.php (published via vendor:publish).
   • Channels: Explore app/Notifications/Channels/ (auto-discovered).
   • Migrations: Check database/migrations/ for notification-related tables.

Implementation Patterns

Core Workflows

1. Defining Notifications:

   • Use the Notification class to create reusable notification types:

     class OrderConfirmation extends Notification
     {
         public function __construct($orderId)
         {
             $this->orderId = $orderId;
         }
     
         public function to($channel)
         {
             return $channel->setData(['order_id' => $this->orderId]);
         }
     }
     

2. Channel Integration:

   • Email: Use EmailChannel with customizable templates:

     $notification->to(new EmailChannel('user@example.com'))
                  ->setTemplate('emails.order_confirmation');
     

   • Slack/Webhook: Extend WebhookChannel for custom APIs:

     $notification->to(new SlackChannel('https://hooks.slack.com/...'))
                  ->setPayload(['text' => 'New alert!']);
     

3. Batch Processing:

   • Send to multiple recipients efficiently:

     $users = User::where('role', 'admin')->get();
     foreach ($users as $user) {
         $notification->to(new EmailChannel($user->email))->send();
     }
     // Or use a queue for async processing:
     $notification->to(new EmailChannel($user->email))->delay(60)->send();
     

4. Dynamic Content:

   • Use view composers or inline data:

     $notification->setData(['user' => $user, 'count' => 5])
                  ->to(new EmailChannel($user->email));
     

5. Event-Driven Triggers:

   • Attach notifications to Laravel events:

     event(new OrderPlaced($order));
     // In EventServiceProvider:
     OrderPlaced::listen(function ($event) {
         $notification = new OrderConfirmation($event->order->id);
         $notification->to(new EmailChannel($event->user->email))->send();
     });
     

Gotchas and Tips

Pitfalls

1. Channel Misconfiguration:

   • Ensure channels are properly registered in config/notifications.php under channels.
   • Debugging tip: Use dd($channel->validate()) to check channel setup.

2. Migration Conflicts:

   • If manually publishing migrations, verify table names (notifications, notification_recipients) don’t clash with existing tables.
   • Run php artisan migrate:status to check for conflicts.

3. Queue Stuck Jobs:

   • Notifications sent via queues may fail silently. Monitor failed_jobs table and set up a dead-letter queue handler.

4. Template Caching:

   • Clear views after updating notification templates:

     php artisan view:clear
     

Debugging Tips

• Log Notifications: Add a LogChannel for debugging:

  $notification->to(new LogChannel())->send(); // Logs to storage/logs/laravel.log
  

• Inspect Payloads: Use dd($notification->getPayload()) to verify data before sending.

Extension Points

1. Custom Channels:

   • Extend Moox\Notifications\Channels\BaseChannel:

     class CustomChannel extends BaseChannel
     {
         public function send($notifiable, $notification)
         {
             // Custom logic (e.g., SMS API call)
         }
     }
     

   • Register in config/notifications.php:

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

2. Middleware:

   • Add middleware to notifications (e.g., rate limiting):

     $notification->via(new RateLimitMiddleware(5, 'minute'));
     

3. Testing:

   • Mock channels in tests:

     $channel = Mockery::mock(EmailChannel::class);
     $channel->shouldReceive('send')->once();
     $notification->to($channel)->send();
     

Config Quirks

• Default Channel: Set a fallback channel in config/notifications.php:

  'default' => 'email',
  

• Recipient Limits: Adjust max_recipients in config to prevent memory issues for bulk sends.

Performance

• Batch Inserts: For bulk notifications, use chunking:

  User::chunk(100, function ($users) {
      foreach ($users as $user) {
          $notification->to(new EmailChannel($user->email))->send();
      }
  });