Notification Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require ehann/notification-bundle:1.*
   

   Add to config/bundles.php (Symfony 4+):

   Ehann\NotificationBundle\EhannNotificationBundle::class => ['all' => true],
   

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

   use Ehann\NotificationBundle\Notification\NotificationManager;
   
   public function someAction(NotificationManager $notificationManager)
   {
       $notificationManager->addSuccess('Operation completed!');
       // or: addError(), addWarning(), addInfo()
   }
   

3. Where to Look First:

   • Usage Documentation
   • src/Ehann/NotificationBundle/Resources/views/Notification/notification.html.twig (default template)
   • config/packages/ehann_notification.yaml (if it exists; otherwise, check for bundle-specific config).

Implementation Patterns

Core Workflow

1. Triggering Notifications: Inject NotificationManager into controllers/services and use methods like:

   $notificationManager->addSuccess('Message', ['key' => 'value']);
   $notificationManager->addError('Error occurred!', [], 'custom_id');
   

2. Customizing Appearance: Override the Twig template (notification.html.twig) in your theme:

   {# Example: Extend with icons #}
   {% extends 'EhannNotificationBundle::Notification/notification.html.twig' %}
   {% block icon %}
       {% if type == 'success' %}
           <i class="fas fa-check-circle"></i>
       {% endif %}
   {% endblock %}
   

3. Flash vs. Persistent Notifications:

   • Flash notifications (default): Clear after one request.
   • For persistent notifications, store them in the session manually and render them in a base template:

     {% for notification in app.notifications %}
         {% include 'EhannNotificationBundle::Notification/notification.html.twig' %}
     {% endfor %}
     

4. Integration with Forms: Validate form submissions and flash errors:

   if (!$form->isValid()) {
       foreach ($form->getErrors(true) as $error) {
           $notificationManager->addError($error->getMessage());
       }
   }
   

5. Dependency Injection: Extend the bundle’s services (e.g., add a custom notification type):

   # config/services.yaml
   services:
       App\Notification\CustomNotifier:
           arguments:
               - '@ehann_notification.notification_manager'
   

Gotchas and Tips

Pitfalls

1. Symfony 4+ Compatibility:

   • The bundle is designed for Symfony 2/3. Some features (e.g., autowiring) may require manual adjustments.
   • Fix: Use NotificationManagerInterface for type-hinting and configure autowiring in config/services.yaml:

     Ehann\NotificationBundle\Notification\NotificationManagerInterface: '@ehann_notification.notification_manager'
     

2. Template Overrides:

   • If the template isn’t rendering, ensure your override is in the correct location (e.g., templates/bundles/EhannNotification/Notification/notification.html.twig).
   • Debug Tip: Clear cache (php bin/console cache:clear) after template changes.

3. Session Dependencies:

   • Notifications rely on the session. If using HTTP caching or stateless APIs, they won’t work.
   • Workaround: Use a database-backed solution for persistent notifications.

4. Type-Specific Styling:

   • The bundle provides success, error, warning, and info types. Custom types (e.g., alert) require CSS classes in the template:

     {% if type == 'alert' %}
         <div class="alert alert-danger">...</div>
     {% endif %}
     

5. Legacy Symfony 2 Features:

   • The bundle uses Symfony 2’s event system. In Symfony 4+, ensure the FrameworkBundle is loaded for compatibility.

Tips

1. Reusable Notification Components: Create a base controller to avoid repetition:

   abstract class BaseController extends AbstractController
   {
       protected NotificationManager $notificationManager;
   
       public function __construct(NotificationManager $notificationManager)
       {
           $this->notificationManager = $notificationManager;
       }
   
       protected function flashSuccess(string $message): void
       {
           $this->notificationManager->addSuccess($message);
       }
   }
   

2. Localization: Translate messages in your templates:

   {{ 'notification.success'|trans({ 'message': message }, 'messages') }}
   

3. Testing: Mock NotificationManager in PHPUnit:

   $notificationManager = $this->createMock(NotificationManagerInterface::class);
   $notificationManager->expects($this->once())
       ->method('addSuccess')
       ->with('Expected message');
   

4. Extending Notification Types: Add a custom type by extending the manager:

   class ExtendedNotificationManager extends NotificationManager
   {
       public function addAlert(string $message, array $parameters = [], string $key = null): void
       {
           $this->addNotification('alert', $message, $parameters, $key);
       }
   }
   

   Register it as a service:

   services:
       App\Notification\ExtendedNotificationManager: '@ehann_notification.notification_manager'
   

5. Performance: For high-traffic apps, avoid storing large notification data in the session. Use short messages or IDs to reference data elsewhere.