Bdf Queue Messenger Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require b2pweb/bdf-queue-messenger-bundle
   

   Add to config/bundles.php:

   Bdf\QueueMessengerBundle\BdfQueueMessengerBundle::class => ['all' => true],
   

2. Configure Messenger: Edit config/packages/messenger.yaml:

   framework:
       messenger:
           transports:
               async: 'bdfqueue://my_bus?consumer_timeout=1&stamp_serializer=null'
   

3. First Use Case: Dispatch a message to the async transport:

   use Symfony\Component\Messenger\MessageBusInterface;
   
   public function __construct(private MessageBusInterface $bus) {}
   
   public function sendEmail(): void
   {
       $this->bus->dispatch(new SendEmailMessage('user@example.com'));
   }
   

4. Run Worker:

   php bin/console messenger:consume async -vv
   

Implementation Patterns

Core Workflow

1. Transport Configuration: Define transports in messenger.yaml:

   transports:
       async: 'bdfqueue://my_bus?consumer_timeout=1&stamp_serializer=null'
       sync: 'bdfqueue://my_bus?consumer_timeout=0'  # Sync processing
   

   • consumer_timeout: Delay in seconds between consumer checks (0 = immediate).
   • stamp_serializer: Disable if using custom serialization.

2. Message Handling: Create a message class and handler:

   // src/Message/SendEmailMessage.php
   class SendEmailMessage implements MessageInterface {
       public function __construct(private string $email) {}
       public function getEmail(): string { return $this->email; }
   }
   
   // src/MessageHandler/SendEmailHandler.php
   class SendEmailHandler {
       public function __invoke(SendEmailMessage $message) {
           // Logic to send email
       }
   }
   

3. Routing Messages: Route messages to specific transports:

   framework:
       messenger:
           routing:
               'App\Message\SendEmailMessage': async
               'App\Message\UrgentEmailMessage': sync
   

4. Worker Management:

   • Run workers in separate processes/terminals:

     php bin/console messenger:consume async --limit=10  # Process 10 messages
     

   • Use --time-limit to control runtime.

5. Retry Logic: Configure retry middleware in messenger.yaml:

   framework:
       messenger:
           failure_transport: failed
           transports:
               failed: 'bdfqueue://failed_bus'
           middleware:
               - 'doctrine_transaction'  # Auto-retry on failure
   

Integration Tips

• Symfony Services: Inject MessageBusInterface into services for async operations.
• Doctrine Integration: Use doctrine_transaction middleware for database consistency.
• Custom Transports: Extend Bdf\Queue\Transport\AbstractTransport for custom queue backends.
• Monitoring: Log message processing with Symfony\Component\Messenger\Stamp\SentToTransportStamp.

Gotchas and Tips

Pitfalls

1. Worker Stuck in Loop:

   • Cause: consumer_timeout=0 with no delay logic.
   • Fix: Set consumer_timeout to a small value (e.g., 1) or use --limit.

2. Serialization Errors:

   • Cause: Custom message classes without __serialize()/__unserialize().
   • Fix: Implement MessageInterface or configure stamp_serializer: null.

3. Failed Messages:

   • Cause: Unhandled exceptions in message handlers.
   • Fix: Configure failure_transport and check failed queue:

     php bin/console messenger:consume failed
     

4. Missing Dependencies:

   • Cause: b2pweb/bdf-queue not installed (required for dev).
   • Fix: Add to composer.json:

     "require-dev": {
         "b2pweb/bdf-queue": "^1.0"
     }
     

Debugging

• Log Messages: Enable debug mode and check var/log/dev.log for messenger events.
• Inspect Queues: Use bdf-queue CLI tools (if installed) to list messages:

  php bin/console bdf:queue:list
  

• Symfony Profiler: Install symfony/messenger profiler for real-time monitoring.

Extension Points

1. Custom Transport: Extend Bdf\Queue\Transport\AbstractTransport and register via DI:

   services:
       App\Transport\CustomTransport:
           tags: ['messenger.transport']
   

2. Middleware: Add custom middleware to messenger.yaml:

   middleware:
       - 'App\Middleware\LogMessageMiddleware'
   

3. Stamp Handling: Use Symfony\Component\Messenger\Stamp\StampInterface for metadata (e.g., timestamps, retries).

4. Configuration Overrides: Override bundle config via config/packages/bdf_queue_messenger.yaml:

   bdf_queue_messenger:
       default_bus: 'my_custom_bus'