Customer Notifications Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require common-gateway/customer-notifications-bundle
   

   Add to config/bundles.php:

   return [
       CommonGateway\CustomerNotificationsBundle\CustomerNotificationsBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php artisan vendor:publish --provider="CommonGateway\CustomerNotificationsBundle\CustomerNotificationsBundle" --tag="config"
   

   Update config/customer_notifications.php with your API keys (e.g., Twilio, Mailgun, WhatsApp Business API).

3. First Use Case Send a test email via a controller:

   use CommonGateway\CustomerNotificationsBundle\Service\NotificationService;
   
   public function sendTestNotification(NotificationService $notificationService)
   {
       $notificationService->sendEmail(
           'user@example.com',
           'Welcome!',
           'Hello, this is a test email.'
       );
   }
   

Key Files to Review

• config/customer_notifications.php: Channel configurations (e.g., SMTP, Twilio, WhatsApp).
• src/Service/NotificationService.php: Core service for sending notifications.
• src/Event/NotificationSentEvent.php: Events for post-send logic (e.g., logging, analytics).

Implementation Patterns

Workflows

1. Channel-Agnostic Notifications Use a unified interface for all channels:

   $notificationService->send(
       'user@example.com', // Recipient (format depends on channel)
       'order_confirmation',
       [
           'template' => 'emails.order_confirmation',
           'data' => ['order_id' => 123],
           'channel' => 'email', // or 'sms', 'whatsapp', 'slack', etc.
       ]
   );
   

2. Template-Based Emails/SMS Store templates in resources/views/emails/ or resources/views/sms/. Pass data dynamically:

   $notificationService->sendEmail(
       'user@example.com',
       'order_confirmation',
       ['order' => $order]
   );
   

3. Event-Driven Notifications Trigger notifications via events (e.g., after order creation):

   event(new OrderCreated($order));
   // In an event listener:
   public function handle(OrderCreated $event)
   {
       $this->notificationService->send($event->order->email, 'order_created', [...]);
   }
   

4. Bulk Notifications Use queues for async processing:

   $notificationService->sendBulk(
       ['user1@example.com', 'user2@example.com'],
       'promotion',
       ['promo_code' => 'SAVE20']
   );
   

Integration Tips

• Laravel Mailables: Extend CommonGateway\CustomerNotificationsBundle\Mail\Mailable for custom logic.
• Queue Workers: Run php artisan queue:work to process notifications in the background.
• Testing: Use NotificationService mocks in PHPUnit:

  $mock = $this->createMock(NotificationService::class);
  $mock->method('send')->willReturn(true);
  

Gotchas and Tips

Pitfalls

1. Channel-Specific Recipient Formats

   • Email: user@example.com
   • SMS/WhatsApp: Phone number as string (e.g., "31612345678").
   • Slack: Webhook URL or channel name (e.g., "#general"). Fix: Validate recipients before sending or use a wrapper method.

2. Rate Limits Channels like WhatsApp or SMS have strict rate limits. Implement retries with exponential backoff:

   $notificationService->sendWithRetry(
       'whatsapp',
       '+31612345678',
       'message',
       3 // Max retries
   );
   

3. Template Caching Clear views cache after updating templates:

   php artisan view:clear
   

4. Missing Default Config If channels fail silently, check config/customer_notifications.php for missing API keys or misconfigured drivers.

Debugging

• Enable Logging Add to config/customer_notifications.php:

  'log' => [
      'enabled' => true,
      'channel' => 'single',
  ],
  

  Check logs in storage/logs/laravel.log.

• Test Mode Use NOTIFICATION_TEST_MODE=true in .env to bypass actual sends (logs to storage/logs/notification_test.log).

Extension Points

1. Custom Channels Implement CommonGateway\CustomerNotificationsBundle\Channel\ChannelInterface:

   class PushChannel implements ChannelInterface {
       public function send($recipient, $message) {
           // Push notification logic (e.g., Firebase)
       }
   }
   

   Register in config/customer_notifications.php:

   'channels' => [
       'push' => [
           'driver' => 'push',
           'config' => [...],
       ],
   ],
   

2. Pre/Post-Send Hooks Subscribe to events:

   NotificationSent::dispatch($notification);
   

   Listen in EventServiceProvider:

   protected $listen = [
       NotificationSent::class => [
           \App\Listeners\LogNotification::class,
       ],
   ];
   

3. Dynamic Recipient Resolution Override resolveRecipient() in a custom notification class to fetch recipients from a database:

   public function resolveRecipient()
   {
       return User::find($this->userId)->email;
   }