Message Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation via utils/prepare_vendors script (recommended): Run the project-specific script to symlink the bundle into /src/Awaresoft.

   ./utils/prepare_vendors
   

   Verify symlink exists at src/Awaresoft/MessageBundle.

2. Manual Symlink (if not using the script): Clone the repo into /vendor/awaresoft/message-bundle and create a symlink:

   ln -s /path/to/message-bundle/src/Awaresoft /src/Awaresoft
   

3. Register the Bundle in app/AppKernel.php:

   new Awaresoft\MessageBundle\AwaresoftMessageBundle(),
   

4. First Use Case: Sending a Message Inject the message.manager service and use the API:

   use Awaresoft\MessageBundle\Message\MessageManager;
   
   class MyController extends Controller
   {
       public function sendMessage(MessageManager $messageManager)
       {
           $message = $messageManager->createMessage('email');
           $message->setTo('user@example.com')
                   ->setSubject('Hello!')
                   ->setBody('Test message');
           $messageManager->send($message);
       }
   }
   

Implementation Patterns

Core Workflows

1. Message Creation & Dispatch

   • Use MessageManager to create and send messages (email, SMS, etc.):

     $message = $messageManager->createMessage('email', [
         'template' => 'emails/welcome.twig',
         'context'  => ['name' => 'John']
     ]);
     $messageManager->send($message);
     

   • Templates: Store Twig templates in Resources/views/ (e.g., emails/welcome.twig).

2. Queue Integration

   • Configure awaresoft_message.yml to use Symfony’s Messenger component:

     awaresoft_message:
         transport: 'doctrine://default'
         transports:
             async: '%env(MESSENGER_TRANSPORT_DSN)%'
     

   • Dispatch messages asynchronously:

     $messageManager->send($message, ['transport' => 'async']);
     

3. Event Listeners

   • Extend functionality via events (e.g., MessageSentEvent):

     // src/Awaresoft/MessageBundle/EventListener/MyListener.php
     class MyListener
     {
         public function onMessageSent(MessageSentEvent $event)
         {
             // Log or process sent messages
         }
     }
     

   • Register in services.yml:

     services:
         my.listener:
             class: AppBundle\EventListener\MyListener
             tags:
                 - { name: kernel.event_listener, event: message.sent, method: onMessageSent }
     

4. Fixtures & Testing

   • Use doctrine-fixtures-bundle to load test messages:

     // src/AppBundle/DataFixtures/ORM/LoadMessageFixture.php
     public function load(ObjectManager $manager)
     {
         $message = $this->messageManager->createMessage('email');
         $message->setTo('test@example.com');
         $manager->persist($message);
         $manager->flush();
     }
     

Gotchas and Tips

Pitfalls

1. Symlink Breakage

   • If composer update runs, it may overwrite symlinks. Solution:
     • Remove the package from composer.json and vendor/ before symlinking.
     • Re-run composer dump-autoload after changes.

2. Backward Compatibility (BC) Risks

   • The bundle enforces strict BC rules. Avoid:
     • Modifying core classes (e.g., MessageManager) without version bumps.
     • Breaking existing templates or configurations.

3. Transport Misconfigurations

   • If messages fail silently, check:
     • awaresoft_message.yml for correct transport DSN.
     • Symfony’s Messenger logs (var/log/dev.log).

4. Template Paths

   • Twig templates must be in Resources/views/ (not templates/). Fix:

     # awaresoft_message.yml
     templates_dir: '%kernel.project_dir%/src/Awaresoft/MessageBundle/Resources/views'
     

Debugging Tips

1. Enable Messenger Debugging Add to config/packages/messenger.yaml:

   messenger:
       transports:
           async: '%env(MESSENGER_TRANSPORT_DSN)%'
       routing:
           'Awaresoft\MessageBundle\Message\Message': async
   

   Check failed messages in the failed_messages table (Doctrine transport).

2. Log Events Enable event logging in config/packages/dev/monolog.yaml:

   handlers:
       message_events:
           type: stream
           path: '%kernel.logs_dir%/message_events.log'
           channels: ['message']
   

3. Common Errors & Fixes

   Error	Solution
   Class not found	Run composer dump-autoload.
   Template not found	Verify templates_dir in config.
   Transport not configured	Check awaresoft_message.yml transport.

Extension Points

1. Custom Message Types Extend Awaresoft\MessageBundle\Message\AbstractMessage:

   class CustomMessage extends AbstractMessage
   {
       protected $customField;
       // Add getters/setters
   }
   

   Register in services.yml:

   services:
       custom.message:
           class: AppBundle\Message\CustomMessage
           tags: ['awaresoft.message.type', { alias: 'custom' }]
   

2. Override Templates Place custom templates in app/Resources/AwaresoftMessageBundle/views/ to override defaults.

3. Add Transport Adapters Implement Awaresoft\MessageBundle\Transport\TransportInterface for new transports (e.g., Slack):

   class SlackTransport implements TransportInterface
   {
       public function send(Message $message) { /* ... */ }
   }
   

   Register in services.yml:

   services:
       slack.transport:
           class: AppBundle\Transport\SlackTransport
           tags: ['awaresoft.message.transport', { alias: 'slack' }]