Rabbitmq Bundle Bridge Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle Add to composer.json:

   composer require dlakomski/rabbitmq-bundle-bridge
   

   Enable in config/bundles.php:

   return [
       // ...
       SimpleBus\RabbitMQBundleBridgeBundle\SimpleBusRabbitMQBundleBridgeBundle::class => ['all' => true],
   ];
   

2. Configure RabbitMQBundle Ensure RabbitMQBundle is installed and configured in config/packages/rabbit_mq.yaml:

   rabbit_mq:
       hosts:
           default:
               host:     'localhost'
               port:     5672
               user:     'guest'
               password: 'guest'
               vhost:    '/'
   

3. First Use Case: Publishing a Message Define a command handler and publish a message:

   use SimpleBus\Message\Bus\CommandBus;
   use App\Messages\PublishMessage;
   
   class MyCommandHandler
   {
       public function __construct(private CommandBus $commandBus) {}
   
       public function handle(): void
       {
           $this->commandBus->dispatch(new PublishMessage('Hello RabbitMQ!'));
       }
   }
   

4. Consuming Messages Create a message handler and register it as a service:

   use SimpleBus\Message\Bus\MessageBus;
   use App\Messages\PublishMessage;
   
   class PublishMessageHandler
   {
       public function __construct(private MessageBus $messageBus) {}
   
       public function __invoke(PublishMessage $message): void
       {
           // Handle the message (e.g., log, process, etc.)
           info('Received: ' . $message->getContent());
       }
   }
   

   Register the handler in config/services.yaml:

   services:
       App\Messages\PublishMessageHandler:
           tags:
               - { name: 'simple_bus.message_handler', handles: App\Messages\PublishMessage }
   

Implementation Patterns

Workflows

1. Decoupled Messaging Use commands/messages to decouple producers (e.g., controllers, cron jobs) from consumers (e.g., workers, services). Example:

   // Producer (e.g., in a controller)
   $this->commandBus->dispatch(new ProcessOrder($orderId));
   
   // Consumer (registered as a service)
   class ProcessOrderHandler
   {
       public function __invoke(ProcessOrder $command): void
       {
           // Business logic here
       }
   }
   

2. Background Processing Offload long-running tasks to RabbitMQ queues:

   # config/packages/rabbit_mq.yaml
   rabbit_mq:
       consumers:
           process_order:
               connection: default
               queue: process_order
               callback: App\Messages\ProcessOrderHandler
               qos: 10  # Prefetch count for fairness
   

3. Event-Driven Architecture Publish domain events and let consumers react:

   // Publish an event
   $this->eventBus->dispatch(new OrderCreated($orderId));
   
   // Handle the event
   class OrderCreatedHandler
   {
       public function __invoke(OrderCreated $event): void
       {
           // Trigger side effects (e.g., notifications, analytics)
       }
   }
   

Integration Tips

• Laravel Service Container Bind SimpleBus interfaces to Laravel’s container in config/services.yaml:

  services:
      SimpleBus\Message\Bus\CommandBus: '@simple_bus.command_bus'
      SimpleBus\Message\Bus\QueryBus: '@simple_bus.query_bus'
      SimpleBus\Message\Bus\EventBus: '@simple_bus.event_bus'
  

• Middleware for Commands/Queries Use SimpleBus middleware (e.g., logging, validation) via config/packages/simple_bus.yaml:

  simple_bus:
      command_bus:
          middleware:
              - SimpleBus\Middleware\LogMessages
              - App\Middleware\ValidateOrderCommand
  

• Retry Logic Leverage RabbitMQ’s dead-letter exchanges (DLX) for failed messages:

  rabbit_mq:
      producers:
          default:
              exchange:
                  name: 'orders'
                  type: direct
                  durable: true
                  dead_letter_exchange: 'orders.dlx'
  

Gotchas and Tips

Pitfalls

1. Connection Management

   • RabbitMQBundle requires a running RabbitMQ server. Test locally with Docker:

     docker run -d --name rabbitmq -p 5672:5672 -p 15672:15672 rabbitmq:management
     

   • Ensure credentials in rabbit_mq.yaml match your setup.

2. Message Serialization

   • By default, messages are serialized with PHP’s serialize(). For custom serialization (e.g., JSON), configure a custom encoder:

     simple_bus:
         command_bus:
             encoder: App\Encoder\JsonEncoder
     

3. Consumer Lifecycle

   • Consumers must be registered as services with the simple_bus.message_handler tag.
   • Avoid circular dependencies between producers/consumers (e.g., a command handler dispatching another command).

4. Queue Binding

   • Explicitly bind queues to exchanges in rabbit_mq.yaml:

     rabbit_mq:
         consumers:
             process_order:
                 queue: process_order
                 binding:
                     exchange: orders
                     routing_key: process.order
     

Debugging

• Check Queue Status Use the RabbitMQ management UI (http://localhost:15672) to inspect queues, messages, and consumers.
• Log Middleware Enable logging middleware to trace message flow:

  simple_bus:
      command_bus:
          middleware:
              - SimpleBus\Middleware\LogMessages
  

• Consumer Errors Failed messages land in the DLX. Configure a consumer for the DLX to inspect failures:

  rabbit_mq:
      consumers:
          dead_letter_consumer:
              queue: orders.dlx
              callback: App\Consumer\DeadLetterConsumer
  

Extension Points

1. Custom Message Classes Extend SimpleBus\Message\Message or use plain PHP objects (annotate with @Message for metadata).
2. Dynamic Routing Use dynamic routing keys based on message properties:

   class OrderProcessed implements Message
   {
       public function __construct(private string $orderId) {}
   
       public function routingKey(): string
       {
           return "order.processed.{$this->orderId}";
       }
   }
   

3. Plugin Architecture Combine with other bundles (e.g., enqueue/amqp-ext for advanced features like batching).