Clarc Message Bus Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require artox-lab/clarc-message-bus-bundle
   

   Enable in config/bundles.php:

   ArtoxLab\Bundle\ClarcMessageBusBundle\ArtoxLabClarcMessageBusBundle::class => ['all' => true],
   

2. Configure Core Dependencies Define your event library (e.g., your-lib/bus-event-message) in config/services.yaml:

   app_message_bus.producer.bus_event_message_factory:
       class: YourLib\BusEventMessage\V1\BusMessageFactory
   ArtoxLab\AbstractBusEventMessage\V1\BusMessageFactoryInterface: '@app_message_bus.producer.bus_event_message_factory'
   

3. First Use Case: Publish an Event Create a custom event (extending BaseEvent from your library) and dispatch it:

   use YourLib\BusEventMessage\V1\Events\BaseEvent;
   
   class OrderCreatedEvent extends BaseEvent {
       public function __construct(public string $orderId) {}
   }
   
   // Dispatch via Messenger
   $this->bus->dispatch(new OrderCreatedEvent('123'));
   

Implementation Patterns

Core Workflow: Event-Driven Architecture

1. Event Creation Extend BaseEvent from your library (e.g., YourLib\BusEventMessage\V1\Events\BaseEvent) for all domain events. Example:

   class UserRegisteredEvent extends BaseEvent {
       public function __construct(public string $userId, public string $email) {}
   }
   

2. Message Serialization Configure messenger.yaml to use the bundle’s serializer:

   transports:
       rabbitmq:
           serializer: artox_lab_clarc_message_bus.transport.bus_serializer
   

3. Middleware Integration Add middleware (e.g., retry logic) in messenger.yaml:

   buses:
       message.bus:
           middleware:
               - validation
               - artox_lab_clarc_message_bus.middleware.add_redelivery_stamp_middleware
   

4. Routing Events Route events to specific transports (e.g., RabbitMQ):

   routing:
       'YourLib\BusEventMessage\V1\Events\UserRegisteredEvent': [rabbitmq]
   

5. Consumption Use Symfony Messenger’s MessageBus to consume events:

   use Symfony\Component\Messenger\MessageBusInterface;
   
   class OrderHandler {
       public function __invoke(OrderCreatedEvent $event, MessageBusInterface $bus) {
           // Handle event logic
       }
   }
   

Integration Tips

• Dependency Injection: Bind your event library’s interfaces to concrete implementations in services.yaml.
• Transport Setup: For RabbitMQ topic exchanges, use RabbitMqBundle to auto-create queues:

  php bin/console rabbitmq:setup-fabric
  php bin/console messenger:setup-transports
  

• Validation: Leverage Symfony’s validation middleware for incoming messages.

Gotchas and Tips

Pitfalls

1. Missing Event Library The bundle requires a custom event library (e.g., artox-lab/abstract-bus-event-message). Forgetting to configure this in services.yaml will cause runtime errors. Fix: Ensure all interfaces (BusMessageFactoryInterface, BusMessageInterface, EventInterface) are bound to your library’s implementations.

2. RabbitMQ Topic Exchange Quirks

   • Auto-Queue Creation: Symfony Messenger does not auto-create queues for topic exchanges. Use RabbitMqBundle or manually configure queues.
   • Binding Keys: Ensure binding keys (e.g., # for wildcards) match your event routing. Fix: Run php bin/console rabbitmq:setup-fabric after defining exchanges.

3. Middleware Order Matters The add_redelivery_stamp_middleware must be last in the middleware chain to correctly stamp messages for retries. Fix: Place it after validation but before doctrine or failed middleware.

4. Serialization Issues Custom event classes must be serializable (e.g., no closures, resources). Use __serialize()/__unserialize() if needed. Fix: Extend BaseEvent and ensure all properties are public or use getters/setters.

Debugging Tips

• Check Transport DSN: Verify %env(RABBITMQ_TRANSPORT_DSN)% is correctly set in .env.
• Log Middleware: Enable Symfony’s logger middleware to debug message flow:

  messenger:
      buses:
          message.bus:
              middleware:
                  - validation
                  - logger  # Add this for debugging
  

• Test Locally: Use symfony/messenger:transport:list and symfony/messenger:consume commands to verify setup.

Extension Points

1. Custom Middleware Extend the bundle’s middleware (e.g., AddRedeliveryStampMiddleware) by creating a new middleware class and adding it to messenger.yaml:

   buses:
       message.bus:
           middleware:
               - your_namespace.middleware.custom_middleware
   

2. Transport Serializer Override the default serializer by binding a custom class to artox_lab_clarc_message_bus.transport.bus_serializer in services.yaml.

3. Event Metadata Add metadata to events via BaseEvent (e.g., getMessageId(), getOccurredOn()) for traceability in logs.