Notification Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require atakajlo/notification-bundle
   

   Add the bundle to config/bundles.php (Symfony):

   return [
       // ...
       Atakajlo\NotificationBundle\AtakajloNotificationBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console atakajlo:notification:install
   

   Edit config/packages/atakajlo_notification.yaml to define channels (e.g., email, centrifugal, database).

3. First Notification Create a notification class (e.g., src/Notification/WelcomeNotification.php):

   namespace App\Notification;
   
   use Atakajlo\NotificationBundle\Notification\NotificationInterface;
   
   class WelcomeNotification implements NotificationInterface
   {
       public function getChannel(): string
       {
           return 'email'; // Matches config key
       }
   
       public function getData(): array
       {
           return [
               'title' => 'Welcome!',
               'message' => 'Thanks for signing up.',
           ];
       }
   }
   

4. Trigger a Notification

   use Atakajlo\NotificationBundle\Notification\NotificationManager;
   
   $notificationManager = $container->get(NotificationManager::class);
   $notificationManager->send(new WelcomeNotification(), $userId);
   

Where to Look First

• Config: config/packages/atakajlo_notification.yaml (channels, drivers, Centrifugo settings).
• Commands: php bin/console list atakajlo (e.g., atakajlo:notification:install, atakajlo:notification:send-test).
• Notification Classes: Extend NotificationInterface in src/Notification/.
• Templates: Override Twig templates in templates/AtakajloNotificationBundle/ (if using email/HTML).

First Use Case: Email + Centrifugo (Real-Time)

1. Configure centrifugal channel in config/packages/atakajlo_notification.yaml:

   channels:
       centrifugal:
           driver: centrifugal
           options:
               url: "http://centrifugo:4000/connection/websocket"
               token: "your-secret-token"
   

2. Create a CentrifugalNotification class:

   class CentrifugalNotification implements NotificationInterface
   {
       public function getChannel(): string { return 'centrifugal'; }
       public function getData(): array { return ['event' => 'new_message', 'data' => [...]]; }
   }
   

3. Send via CLI:

   php bin/console atakajlo:notification:send-test App\Notification\CentrifugalNotification 123
   

Implementation Patterns

Core Workflows

1. Channel-Driven Notifications

• Pattern: Define channels in config, then implement NotificationInterface for each.
• Example:

  # config/packages/atakajlo_notification.yaml
  channels:
      email:
          driver: mail
          options:
              from: "no-reply@example.com"
      sms:
          driver: twilio
          options:
              sid: "your_sid"
              token: "your_token"
  

• Usage:

  class OrderConfirmationNotification implements NotificationInterface
  {
      public function getChannel(): string { return 'email'; }
      public function getData(): array { return ['order_id' => 123]; }
  }
  

2. Dynamic Channel Selection

• Use logic in getChannel() to route based on user preferences or context:

  public function getChannel(): string
  {
      return $this->user->prefersEmail() ? 'email' : 'centrifugal';
  }
  

3. Batch Processing

• Use the send-batch command for bulk notifications:

  php bin/console atakajlo:notification:send-batch App\Notification\WelcomeNotification 1,2,3,4,5
  

4. Event Listeners

• Trigger notifications via Symfony events (e.g., user.registered):

  // src/EventListener/UserRegisteredListener.php
  public function onUserRegistered(UserRegisteredEvent $event)
  {
      $notificationManager->send(new WelcomeNotification(), $event->getUser()->getId());
  }
  

Integration Tips

Laravel-Specific Adaptations

1. Service Container Bind the NotificationManager in config/services.php:

   'notification_manager' => Atakajlo\NotificationBundle\Notification\NotificationManager::class,
   

   Access via:

   $this->container->get('notification_manager');
   

2. Queue Integration Configure the queue driver in config/packages/atakajlo_notification.yaml:

   channels:
       queue:
           driver: queue
           options:
               connection: database
   

   Then dispatch notifications to queues:

   $notificationManager->sendLater(new WelcomeNotification(), $userId, now()->addMinutes(5));
   

3. Custom Drivers Extend Atakajlo\NotificationBundle\Driver\DriverInterface for new channels (e.g., Slack, Push):

   class SlackDriver implements DriverInterface
   {
       public function send(NotificationInterface $notification, $recipient): void
       {
           // Logic to send via Slack Webhook
       }
   }
   

   Register in config:

   channels:
       slack:
           driver: slack
           options:
               webhook_url: "https://hooks.slack.com/..."
   

4. Twig Integration Override email templates in templates/AtakajloNotificationBundle/email/:

   {# templates/AtakajloNotificationBundle/email/welcome.html.twig #}
   <h1>{{ notification.data.title }}</h1>
   <p>{{ notification.data.message }}</p>
   

Gotchas and Tips

Pitfalls

1. Channel Mismatch

   • Issue: NotificationInterface::getChannel() returns a key that doesn’t exist in config.
   • Fix: Validate channel names against config/packages/atakajlo_notification.yaml keys.
   • Debug: Check logs for Channel [X] not configured errors.

2. Centrifugo Connection Issues

   • Issue: Real-time notifications fail silently.
   • Fix:
     • Verify phpcent is installed and Centrifugo server is running.
     • Check options.url and options.token in config.
     • Enable debug mode in config/packages/atakajlo_notification.yaml:

       debug: true
       

3. Proprietary License

   • Issue: License is marked as proprietary (unusual for open-source).
   • Action: Review LICENSE file or contact maintainer for clarification before production use.

4. Queue Stuck Jobs

   • Issue: Notifications dispatched to the queue never process.
   • Fix:
     • Ensure database or redis queue connection is configured in .env.
     • Run php bin/console messenger:consume async (if using Symfony Messenger).

Debugging

1. Enable Debug Mode

   # config/packages/atakajlo_notification.yaml
   debug: true
   

   Logs detailed events to var/log/dev.log.

2. Test Commands

   • Send a test notification:

     php bin/console atakajlo:notification:send-test App\Notification\WelcomeNotification 1
     

   • List all notifications:

     php bin/console atakajlo:notification:list
     

3. Driver-Specific Logs

   • For email failures, check Symfony Mailer logs:

     php bin/console debug:mailer:messages
     

   • For Centrifugo, inspect WebSocket connections via browser dev tools or wscat.

Tips

1. Environment-Specific Config Override config per environment (e.g., config/packages/dev/atakajlo_notification.yaml):

   debug: true
   channels:
       centrifugal:
           options:
               url: "ws://localhost:4000/connection/websocket"
   

2. Notification Metadata Add metadata to track notifications (e.g., sent_at, status):

   public function getMetadata(): array
   {
       return [
           'priority' => 'high',
           'template' => 'custom_template',
       ];
   }
   

3. Rate Limiting Use Symfony’s RateLimiter to throttle notifications:

   # config/packages/atakajlo_notification.yaml
   rate_limiter:
       enabled: true
       limit: 10
       interval: 60
   

4. Custom Recipient Mapping Override recipient resolution in NotificationManager: