Notifier Client Bundle Laravel Package

Getting Started

Minimal Setup

1. Install via Composer:

   composer require coka/notifier-client-bundle
   

2. Enable the Bundle in config/bundles.php:

   return [
       // ...
       CedrickOka\NotifierClientBundle\CokaNotifierClientBundle::class => ['all' => true],
   ];
   

3. Configure in config/packages/coka_notifier_client.yaml (default config provided).
4. First Use Case: Inject the NotifierClient service and send a notification:

   use CedrickOka\NotifierClientBundle\Notifier\NotifierClient;
   
   class MyController extends AbstractController
   {
       public function __construct(private NotifierClient $notifier)
       {
       }
   
       public function sendNotification()
       {
           $this->notifier->send(
               'email', // channel
               'user@example.com', // recipient
               'Welcome!', // subject
               'Hello, this is your notification.' // message
           );
       }
   }
   

Implementation Patterns

Core Workflows

1. Channel-Based Notifications: Use predefined channels (e.g., email, sms, push) or extend with custom channels.

   $this->notifier->send('custom_channel', $recipient, $subject, $message);
   

2. Template-Based Messages: Replace static messages with Twig templates for dynamic content:

   # config/packages/coka_notifier_client.yaml
   templates:
       email:
           welcome: 'emails/welcome.html.twig'
   

   $this->notifier->send('email', 'user@example.com', 'Welcome', [
       'name' => 'John'
   ], 'welcome'); // Uses 'welcome' template
   

3. Batch Processing: Queue notifications for async delivery (if configured):

   $this->notifier->queue('email', 'user@example.com', 'Subject', 'Message');
   

4. Event-Driven Triggers: Dispatch notifications from Symfony events (e.g., KernelEvents::TERMINATE):

   use Symfony\Component\HttpKernel\Event\TerminateEvent;
   use Symfony\Component\HttpKernel\KernelEvents;
   
   $eventDispatcher->addListener(KernelEvents::TERMINATE, function (TerminateEvent $event) {
       $this->notifier->send('email', 'admin@example.com', 'System Alert', 'Check logs!');
   });
   

Integration Tips

• Laravel-Specific: Use Symfony’s HttpKernel bridge to integrate with Laravel’s service container:

  $container->register('notifier', NotifierClient::class)
      ->addArgument($container->getParameter('coka_notifier_client.config'));
  

• Logging: Enable debug logging for failed notifications:

  # config/packages/coka_notifier_client.yaml
  logging: true
  

• Testing: Mock NotifierClient in PHPUnit:

  $mockNotifier = $this->createMock(NotifierClient::class);
  $mockNotifier->expects($this->once())->method('send');
  $this->container->set('notifier', $mockNotifier);
  

Gotchas and Tips

Pitfalls

1. Channel Validation:

   • Undefined channels throw InvalidArgumentException. Always validate channels exist in config:

     if (!$this->notifier->supportsChannel('custom_channel')) {
         throw new \RuntimeException('Channel not configured.');
     }
     

   • Fix: Extend the bundle’s ChannelInterface to add new channels dynamically.

2. Template Resolution:

   • Twig templates must exist in templates/ or a configured path. Missing templates cause silent failures.
   • Debug: Enable debug: true in config to log unresolved templates.

3. Async Queueing:

   • If using queues, ensure coka_notifier_client.queue_connection is configured (e.g., doctrine or symfony).
   • Tip: Test queue consumers locally with:

     php bin/console coka:notifier:consume
     

4. Recipient Sanitization:

   • No built-in validation for email/SMS formats. Add custom validation:

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

Debugging

• Logs: Check var/log/dev.log for notification failures (enable logging: true).
• Dumps: Use Symfony’s var dumper for channel configs:

  dump($this->notifier->getChannel('email')->getConfig());
  

• Events: Listen for NotifierEvents::FAILED to handle errors:

  $eventDispatcher->addListener(NotifierEvents::FAILED, function (NotificationFailedEvent $event) {
      // Handle failure (e.g., retry or alert)
  });
  

Extension Points

1. Custom Channels: Implement CedrickOka\NotifierClientBundle\Notifier\ChannelInterface:

   class SlackChannel implements ChannelInterface
   {
       public function send($recipient, $message): bool
       {
           // Custom logic (e.g., HTTP call to Slack API)
           return true;
       }
   }
   

   Register in config:

   channels:
       slack:
           class: App\Notifier\SlackChannel
           webhook_url: '%env(SLACK_WEBHOOK_URL)%'
   

2. Middleware: Add pre/post-send logic via NotifierEvents::BEFORE_SEND/NotifierEvents::AFTER_SEND:

   $eventDispatcher->addListener(NotifierEvents::BEFORE_SEND, function (NotificationEvent $event) {
       $event->setMessage(strtoupper($event->getMessage()));
   });
   

3. Configuration Overrides: Override default config in config/packages/overrides/coka_notifier_client.yaml:

   default_channel: 'sms'
   channels:
       email:
           from: 'noreply@yourdomain.com'