Getting Started

Minimal Steps to First Use

Install the Bundle Run either:

composer require common-gateway/notifications-bundle:dev-main

or (Docker):

docker-compose exec php composer require common-gateway/notifications-bundle:dev-main

Install Schemas Execute:

php bin/console commongateway:install common-gateway/notifications-bundle

or (Docker):

docker-compose exec php bin/console commongateway:install common-gateway/notifications-bundle

Verify Installation Navigate to the Plugins tab in the Common Gateway admin UI. The NotificationsBundle should appear as an available plugin.

First Use Case: Sending a Notification Use the bundle’s Symfony Messenger integration to dispatch notifications:

use CommonGateway\NotificationsBundle\Message\SendNotification;

$bus->dispatch(new SendNotification(
    'user@example.com',
    'welcome',
    ['name' => 'John']
));

Implementation Patterns

Core Workflows

Plugin-Based Notification Dispatch

Leverage the bundle’s Symfony Messenger integration to decouple notification logic from business logic.

Example workflow:

// Dispatch a notification asynchronously
$bus->dispatch(new SendNotification($recipient, $template, $context));

// Handle the message in a worker (e.g., via Symfony Messenger transport)

Custom Notification Templates
- Extend the bundle’s template system by creating YAML/JSON templates in:
```
config/packages/common_gateway_notifications/templates/
```
- Example template (welcome.yml):
```
subject: "Welcome, {name}!"
body: "Hello {name}, thanks for signing up."
```
Admin UI Integration
- Use the Plugins tab to enable/disable the bundle globally.
- Configure notification channels (e.g., email, SMS) via the admin dashboard under Notifications > Channels.

Event-Driven Extensions

Subscribe to NotificationSentEvent to log or audit notifications:

use CommonGateway\NotificationsBundle\Event\NotificationSentEvent;

$eventDispatcher->addListener(NotificationSentEvent::class, function (NotificationSentEvent $event) {
    // Custom logic (e.g., analytics, retries)
});

Integration Tips

Laravel-Specific Adaptations

Use Laravel’s Bus facade to dispatch messages:

use Illuminate\Bus\Dispatcher;

$dispatcher = app(Dispatcher::class);
$dispatcher->dispatch(new SendNotification(...));

Override the bundle’s NotificationSender service to inject Laravel’s mailers or queues:

// config/services.yaml
CommonGateway\NotificationsBundle\Sender\NotificationSender:
    arguments:
        $mailer: '@mailer'
        $queue: '@queue'

Database Schema Customization

Extend the bundle’s Doctrine entities (e.g., Notification) by adding fields to the notifications table:

# config/packages/doctrine.yaml
orm:
    mappings:
        CommonGatewayNotificationsBundle:
            type: attribute
            dir: "%kernel.project_dir%/vendor/common-gateway/notifications-bundle/Entity"
            prefix: "CommonGateway\NotificationsBundle\Entity"
            alias: CommonGatewayNotificationsBundle

Testing

Mock the NotificationSender in tests:

$this->mock(NotificationSender::class)
    ->shouldReceive('send')
    ->once();

Gotchas and Tips

Pitfalls

Schema Conflicts
- If you customize the notifications table, ensure migrations are idempotent. The bundle’s commongateway:install command may re-run schema updates.
- Fix: Use php bin/console doctrine:migrations:diff to generate safe migrations.
Message Transport Misconfiguration
- Notifications dispatched via Messenger may fail silently if the transport (e.g., doctrine, sync) is misconfigured.
- Debug: Check Symfony’s profiler for failed messages or enable debug logging:
```
# config/packages/monolog.yaml
handlers:
    messenger:
        type: stream
        path: "%kernel.logs_dir%/%kernel.environment%.messenger.log"
        level: debug
```
Template Parsing Errors
- Invalid placeholders (e.g., {undefined_var}) in templates will throw exceptions during rendering.
- Tip: Use Twig’s {{ var|default('fallback') }} or validate templates with:
```
$this->get('common_gateway_notifications.template_resolver')->resolve('welcome');
```
Plugin Discovery Issues
- The bundle must be enabled in the admin UI or via config/packages/common_gateway.yaml:
```
commongateway:
    plugins:
        - common_gateway_notifications
```

Debugging Tips

Enable Verbose Logging
```
php bin/console debug:config common_gateway_notifications
```
Check for missing configurations or overrides.

Inspect Dispatcher Use the Symfony Messenger debug command:

php bin/console messenger:failed:list
php bin/console messenger:consume async -vv

Override Services for Debugging Replace the NotificationSender with a debug version:

# config/services_test.yaml
CommonGateway\NotificationsBundle\Sender\NotificationSender:
    class: App\Debug\DebugNotificationSender

Extension Points

Custom Channels Extend the ChannelInterface to support new delivery methods (e.g., Slack, Webhook):

namespace App\Notifications\Channel;

use CommonGateway\NotificationsBundle\Channel\AbstractChannel;

class SlackChannel extends AbstractChannel
{
    public function send(Notification $notification): void
    {
        // Custom Slack logic
    }
}

channels:
    slack: App\Notifications\Channel\SlackChannel

Event Listeners Hook into the notification lifecycle:

// src/EventListener/NotificationListener.php
use CommonGateway\NotificationsBundle\Event\NotificationSentEvent;

class NotificationListener
{
    public function onNotificationSent(NotificationSentEvent $event)
    {
        // Example: Log to a third-party API
    }
}

Bind the listener in services.yaml:

services:
    App\EventListener\NotificationListener:
        tags:
            - { name: kernel.event_listener, event: CommonGateway\NotificationsBundle\Event\NotificationSentEvent }

Template Overrides Override default templates by placing files in:
```
config/packages/common_gateway_notifications/templates/custom/
```
The bundle will prioritize these over vendor templates.

Notifications Bundle Laravel Package