Enqueue Messenger Adapter Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Package

   composer require enqueue/messenger-adapter
   

2. Configure Enqueue Bundle Add the ENQUEUE_DSN to your .env (e.g., for RabbitMQ):

   ENQUEUE_DSN=amqp://guest:guest@localhost:5672/%2f
   

   Ensure the EnqueueBundle is installed and configured.

3. Define a Message Class Create a simple message class (e.g., app/Message/MyMessage.php):

   namespace App\Message;
   
   class MyMessage {
       public string $content;
       public function __construct(string $content) {
           $this->content = $content;
       }
   }
   

4. Configure Messenger Transport In config/packages/messenger.yaml:

   framework:
       messenger:
           transports:
               amqp: 'enqueue://default'
           routing:
               'App\Message\MyMessage': amqp
   

5. Dispatch a Message In a controller or service:

   use App\Message\MyMessage;
   use Symfony\Component\Messenger\MessageBusInterface;
   
   public function sendMessage(MessageBusInterface $bus) {
       $bus->dispatch(new MyMessage('Hello, Queue!'));
   }
   

6. Consume Messages Run the consumer in a terminal:

   php bin/console messenger:consume-messages amqp
   

Implementation Patterns

Workflow: Producer-Consumer

1. Producer Workflow

   • Dispatch messages via MessageBusInterface in controllers, commands, or services.
   • Route messages to the amqp transport using annotations or YAML routing.
   • Example with annotation:

     use Symfony\Component\Messenger\Attribute\AsMessage;
     #[AsMessage(to: ['amqp'])]
     class MyMessage { ... }
     

2. Consumer Workflow

   • Run consumers in the background (e.g., via messenger:consume-messages).
   • For production, use a process manager (e.g., Supervisor) to keep consumers alive:

     [program:messenger]
     command=php /path/to/bin/console messenger:consume-messages amqp
     autostart=true
     autorestart=true
     

   • Handle failures with retry strategies in messenger.yaml:

     framework:
         messenger:
             failure_transport: failed
             transports:
                 failed: 'doctrine://default?queue_name=failed'
     

3. Integration with Enqueue Brokers

   • Leverage Enqueue’s supported brokers (RabbitMQ, Redis, Amazon SQS, etc.).
   • Customize DSN for specific queues/exchanges:

     transports:
         amqp:
             dsn: 'enqueue://default?queue[routingKey][name]=my_queue&topic[name]=my_topic'
     

4. Async Processing

   • Use handle() in message handlers for synchronous processing:

     use Symfony\Component\Messenger\Attribute\AsMessageHandler;
     
     #[AsMessageHandler]
     public function __invoke(MyMessage $message) {
         // Process $message->content
     }
     

   • For async workers, combine with Enqueue’s consumers.

Gotchas and Tips

Pitfalls

1. DSN Configuration

   • Issue: Incorrect DSN format (e.g., missing enqueue:// prefix) causes silent failures.
   • Fix: Always validate DSN with Enqueue’s DSN documentation.
   • Example: enqueue://default?queue[name]=my_queue (not amqp://...).

2. Consumer Lifecycle

   • Issue: Consumers exit unexpectedly in production if not managed by a process supervisor.
   • Fix: Use Supervisor or Docker to restart consumers on crashes.

3. Message Serialization

   • Issue: Complex objects may fail to serialize if not marked as Serializable or with #[AsMessage].
   • Fix: Use #[AsMessage] or implement Serializable:

     #[AsMessage]
     class MyMessage implements Serializable { ... }
     

4. Routing Conflicts

   • Issue: Messages routed to multiple transports may cause duplicates.
   • Fix: Explicitly define routing in YAML or use annotations:

     routing:
         'App\Message\MyMessage': amqp  # Overrides default
     

5. Old Package Maturity

   • Issue: Last release in 2018 may lack compatibility with newer Symfony/Messenger versions.
   • Fix: Test with your Symfony version (e.g., symfony/messenger:^5.0). Fork or patch if needed.

Debugging Tips

1. Check Consumer Logs Run consumers with verbose output:

   php bin/console messenger:consume-messages amqp -vv
   

2. Inspect Queue State Use Enqueue’s CLI tools (e.g., enqueue:consume) to verify messages:

   php bin/console enqueue:consume --dsn=amqp://guest:guest@localhost:5672/%2f
   

3. Enable Messenger Debug Add to config/packages/dev/messenger.yaml:

   framework:
       messenger:
           transports:
               amqp: 'enqueue://default?debug=true'
   

Extension Points

1. Custom Transport Configuration Extend the transport DSN for advanced broker settings:

   transports:
       amqp:
           dsn: 'enqueue://default?queue[durable]=true&queue[exclusive]=false'
   

2. Middleware Integration Add middleware to messages (e.g., logging, validation):

   framework:
       messenger:
           transports:
               amqp:
                   dsn: 'enqueue://default'
                   middleware:
                       - 'App\Middleware\LogMessageMiddleware'
   

3. Dynamic Routing Use runtime logic to route messages dynamically:

   $bus->dispatch(new MyMessage($content), ['routing_key' => 'dynamic_queue']);