Notification Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require aldaflux/notification-bundle
   

   Ensure DoctrineBundle is installed (required for ORM support).

2. Configuration: Add to config/packages/aldaflux_notification.yaml (if customizing):

   aldaflux_notification:
       notification_class: App\Entity\CustomNotification  # Optional
   

3. First Use Case: Trigger a notification in a controller:

   use Aldaflux\NotificationBundle\Manager\NotificationManager;
   
   public function sendNotification(NotificationManager $manager)
   {
       $notification = $manager->createNotification(
           'Welcome!',
           'Your account is ready.',
           '/dashboard'
       );
       $manager->addNotification([$this->getUser()], $notification, true);
   }
   

Key Classes to Explore

• NotificationManager: Core service for creating/managing notifications.
• Notification: Default entity (extend if needed).
• Twig\Extension\NotificationExtension: For rendering notifications in templates.

Implementation Patterns

Common Workflows

1. Creating Notifications:

   // Basic
   $manager->createNotification('Title', 'Message', 'Link');
   
   // With custom entity
   $customNotif = new CustomNotification();
   $customNotif->setTitle('Custom Title');
   $manager->addNotification([$user], $customNotif);
   

2. Bulk Notifications:

   $users = $userRepository->findBy(['role' => 'admin']);
   $manager->addNotification($users, $notification, false); // false = no auto-flush
   

3. Twig Integration:

   {% for notification in app.user.notifications %}
       <div class="notification">
           <h3>{{ notification.title }}</h3>
           <p>{{ notification.message }}</p>
           <a href="{{ notification.link }}">View</a>
       </div>
   {% endfor %}
   

4. Event-Driven Notifications: Subscribe to Symfony events (e.g., KernelEvents::VIEW) to trigger notifications dynamically:

   $eventDispatcher->addListener(KernelEvents::VIEW, function (ViewEvent $event) {
       if ($event->getRequest()->attributes->get('trigger_notification')) {
           $manager->createNotification(...);
       }
   });
   

5. Customizing Rendering: Extend the Twig extension or override the default template:

   # config/packages/twig.yaml
   twig:
       paths:
           '%kernel.project_dir%/templates/notifications'
   

Gotchas and Tips

Pitfalls

1. Doctrine ORM Dependency:

   • The bundle only supports Doctrine ORM. If using another DBAL, create a custom notification entity with manual persistence.

2. Auto-Flush Behavior:

   • addNotification(..., true) flushes immediately. For bulk operations, disable auto-flush (false) and manually flush later to optimize performance.

3. Translation Quirks:

   • Default translations are limited. Extend the bundle’s translation files (translations/messages.en.xlf) or override them in your project.

4. Notification Entity Lock-In:

   • Customizing the notification entity requires YAML config (see README). Forgetting this step may cause runtime errors.

5. Link Validation:

   • The link field is stored as-is. Validate URLs in your application logic to avoid broken links in notifications.

Debugging Tips

• Check Entity Mapping: If notifications aren’t saved, verify your CustomNotification entity uses the correct annotations (e.g., @ORM\Entity, @ORM\Table).

  use Doctrine\ORM\Mapping as ORM;
  #[ORM\Entity]
  class CustomNotification extends Notification {}
  

• Flush Issues: Use EntityManager::flush() explicitly if auto-flush fails:

  $manager->addNotification($users, $notification, false);
  $entityManager->flush();
  

• Twig Rendering: Clear cache after adding custom templates:

  php bin/console cache:clear
  

Extension Points

1. Custom Notification Types: Extend the Notification entity and register it via config:

   aldaflux_notification:
       notification_class: App\Entity\PriorityNotification
   

2. Add Metadata: Store additional fields (e.g., priority, read_at) by extending the entity:

   #[ORM\Column(type: 'integer')]
   private $priority;
   

3. Notification Channels: Integrate with external services (e.g., email, SMS) by creating a custom listener:

   $eventDispatcher->addListener(NotificationEvents::POST_CREATE, function (NotificationEvent $event) {
       // Send email/SMS via a service
   });
   

4. Batch Processing: For large-scale notifications, use Doctrine’s batch processing:

   $entityManager->getConnection()->beginTransaction();
   try {
       foreach ($users as $user) {
           $manager->addNotification([$user], $notification, false);
       }
       $entityManager->flush();
       $entityManager->getConnection()->commit();
   } catch (\Exception $e) {
       $entityManager->getConnection()->rollBack();
   }