Bdf Queue Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require b2pweb/bdf-queue-bundle
   

2. Enable the Bundle Add to config/bundles.php:

   Bdf\QueueBundle\BdfQueueBundle::class => ['all' => true],
   

3. Configure Environment Set your queue connection URL in .env:

   BDF_QUEUE_CONNETION_URL=gearman://root@127.0.0.1?client-timeout=10
   

4. Basic Config Create config/packages/bdf_queue.yaml with a minimal setup:

   bdf_queue:
     default_connection: 'gearman'
     connections:
       gearman:
         url: '%env(resolve:BDF_QUEUE_CONNETION_URL)%'
   

First Use Case: Sending a Job

1. Define a Destination Add a destination in bdf_queue.yaml:

   destinations:
     bus:
       url: 'queue://gearman/bus'
   

2. Send a Message Use the Bdf\QueueBundle\Producer\ProducerInterface service:

   use Bdf\QueueBundle\Producer\ProducerInterface;
   
   class MyService {
       public function __construct(private ProducerInterface $producer) {}
   
       public function sendMessage() {
           $this->producer->send('bus', 'Hello, Queue!');
       }
   }
   

Implementation Patterns

Core Workflows

1. Producer-Consumer Pattern

   • Produce Jobs: Use ProducerInterface to send messages to destinations.

     $producer->send('destination_name', $message, ['priority' => 1]);
     

   • Consume Jobs: Define a receiver factory (tagged service or ReceiverFactoryProviderInterface) to handle messages.

     services:
       MyReceiverFactory:
         class: App\Receiver\MyReceiverFactory
         tags: ['bdf_queue.receiver_factory']
     

2. Connection Management

   • Custom Drivers: Implement ConnectionDriverConfiguratorInterface for unsupported drivers (e.g., Redis, RabbitMQ).

     class RedisConfigurator implements ConnectionDriverConfiguratorInterface {
         public function configure(ConnectionDriverFactory $factory) {
             $factory->addDriver('redis', new RedisDriver());
         }
     }
     

   • Register via tag or autoconfigure (set autoconfigure: true in bdf_queue.yaml).

3. Middleware Integration

   • Add middleware to the receiver factory (e.g., logging, validation):

     class MyReceiverFactory implements ReceiverFactoryProviderInterface {
         public function getReceiverFactories() {
             $factory = new ReceiverFactory();
             $factory->addMiddleware(new LoggingMiddleware());
             return [$factory];
         }
     }
     

4. Dynamic Destinations

   • Use environment variables or runtime logic to define destinations:

     destinations:
       dynamic_bus:
         url: '%env(resolve:DYNAMIC_QUEUE_URL)%'
     

Integration Tips

• Symfony Messenger Bridge: Combine with symfony/messenger for hybrid workflows.

  # config/packages/messenger.yaml
  framework:
      messenger:
          transports:
              async: '%env(MESSENGER_TRANSPORT_DSN)%'
  

• Retry Logic: Leverage the retry option in consumer config for failed jobs.

  destinations:
    bus:
      consumer:
        retry: 3
  

• Auto-Discovery: Enable auto_handle: true for message-based routing (requires target hints in messages).

Gotchas and Tips

Pitfalls

1. Connection URL Parsing

   • Ensure the URL format matches {driver}+{vendor}://{user}:{password}@{host}:{port}/{queue}.
   • Example: gearman://user:pass@localhost:4730/bus (not gearman://localhost/bus).
   • Fix: Explicitly set host, port, etc., if the URL is malformed.

2. Serializer Mismatch

   • If using bdf or bdf_json serializers, ensure the consumer and producer agree on the format.
   • Debug: Check Bdf\Queue\Serializer\SerializerFactory for supported IDs (native, bdf, bdf_json).

3. Consumer Stuck on Empty Queue

   • stop_when_empty: true halts consumption if no messages arrive within the wait duration.
   • Workaround: Set stop_when_empty: false for long-running consumers.

4. Memory Limits

   • The memory option in consumer config kills the process if exceeded.
   • Tip: Monitor memory usage in production (e.g., with memory_get_usage()).

5. Middleware Order

   • Middleware runs in the order added to ReceiverFactory. Place critical middleware (e.g., validation) early.

Debugging

• Log Consumer Activity Add a logging middleware:

  class LogMiddleware implements MiddlewareInterface {
      public function handle(ReceiveContext $context, callable $next) {
          \Log::info('Message received', ['body' => $context->getMessage()->getBody()]);
          return $next($context);
      }
  }
  

• Check Connection Health Use the Bdf\QueueBundle\ConnectionFactory\ConnectionFactory service to test connections:

  $connection = $connectionFactory->createConnection('gearman');
  if (!$connection->isConnected()) {
      throw new \RuntimeException('Connection failed');
  }
  

• Validate YAML Config Symfony’s ParameterBag throws exceptions for invalid config. Use symfony/var-dumper to inspect parsed config:

  use Symfony\Component\DependencyInjection\ParameterBag\ParameterBagInterface;
  
  $config = $container->getParameter('bdf_queue');
  dump($config);
  

Extension Points

1. Custom Serializers Extend Bdf\Queue\Serializer\SerializerInterface and register via bdf_queue.serializer service ID:

   services:
     app.custom_serializer:
       class: App\Serializer\CustomSerializer
       tags: ['bdf_queue.serializer']
   

2. Queue Drivers Implement Bdf\Queue\Connection\DriverInterface and configure via ConnectionDriverConfiguratorInterface.
3. Receiver Factories Override default factories for complex routing logic:

   class CustomReceiverFactory implements ReceiverFactoryProviderInterface {
       public function getReceiverFactories() {
           return [new class extends ReceiverFactory {
               protected function createReceiver() {
                   return new CustomReceiver();
               }
           }];
       }
   }
   

4. Event Listeners Listen to queue events (e.g., bdf_queue.message.sent, bdf_queue.message.received) via Symfony’s event dispatcher.

Configuration Quirks

• Environment Variables Use %env(resolve:VAR_NAME)% to resolve variables early (avoids runtime errors).
• Default Values The bundle merges config with defaults. Override specific keys to avoid unintended side effects:

  bdf_queue:
    connections:
      gearman:
        options:
          client-timeout: 30  # Overrides URL param if present
  

• Autoconfigure Set autoconfigure: true in bdf_queue.yaml to auto-register services implementing ReceiverFactoryProviderInterface or ConnectionDriverConfiguratorInterface. Disable if you need explicit control.