Enqueue Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require enqueue/enqueue-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       Enqueue\Bundle\EnqueueBundle::class => ['all' => true],
   ];
   

2. Configure a Transport (e.g., Redis):

   # config/packages/enqueue.yaml
   enqueue:
       clients:
           default:
               dsn: 'redis://localhost'
   

3. First Use Case: Define a job class (e.g., app/Jobs/SendEmailJob.php):

   use Enqueue\Client\Job;
   use Enqueue\Util\JSON;
   
   class SendEmailJob implements Job
   {
       public function __construct(private string $email) {}
   
       public function run(): void
       {
           // Logic to send email
       }
   
       public function serialize(): string
       {
           return JSON::encode(['email' => $this->email]);
       }
   
       public static function deserialize(string $data): self
       {
           $result = JSON::decode($data, true);
           return new self($result['email']);
       }
   }
   

   Dispatch the job in a controller:

   use Enqueue\Client\ProducerInterface;
   
   public function __construct(private ProducerInterface $producer) {}
   
   public function sendEmail(): void
   {
       $this->producer->send(new SendEmailJob('user@example.com'));
   }
   

Implementation Patterns

Core Workflows

1. Producer-Consumer Pattern:

   • Producers: Dispatch jobs via ProducerInterface (e.g., in controllers, commands, or services).

     $this->producer->send(new ProcessOrderJob($orderId));
     

   • Consumers: Register consumers as Symfony services with the enqueue.consumer tag:

     services:
         App\Consumer\OrderConsumer:
             tags: ['enqueue.consumer']
     

     class OrderConsumer implements ConsumerInterface
     {
         public function run(): void
         {
             while ($job = $this->client->receive()) {
                 $job->run();
                 $this->client->acknowledge($job);
             }
         }
     }
     

2. Job Serialization:

   • Implement Job interface with serialize()/deserialize() methods.
   • Use Enqueue\Util\JSON for simple types or custom serializers for complex objects.

3. Retry Logic:

   • Configure retry policies in enqueue.yaml:

     enqueue:
         clients:
             default:
                 dsn: 'redis://localhost'
                 retry_strategy:
                     max_attempts: 3
                     delay: 1000
     

4. Delayed Jobs:

   • Schedule jobs with a delay (e.g., for background processing):

     $this->producer->send(new SendEmailJob('user@example.com'), 60); // Delay: 60 seconds
     

Integration Tips

• Symfony Commands: Use consumers in CLI commands for long-running tasks:

  use Symfony\Component\Console\Command\Command;
  use Symfony\Component\Console\Input\InputInterface;
  use Symfony\Component\Console\Output\OutputInterface;
  
  class ProcessQueueCommand extends Command
  {
      protected function execute(InputInterface $input, OutputInterface $output): int
      {
          $this->container->get('enqueue.consumer')->run();
          return Command::SUCCESS;
      }
  }
  

• Event Dispatching: Trigger events after job processing:

  use Symfony\Contracts\EventDispatcher\EventDispatcherInterface;
  
  class OrderConsumer implements ConsumerInterface
  {
      public function __construct(private EventDispatcherInterface $dispatcher) {}
  
      public function run(): void
      {
          while ($job = $this->client->receive()) {
              $job->run();
              $this->dispatcher->dispatch(new JobProcessedEvent($job));
              $this->client->acknowledge($job);
          }
      }
  }
  

Gotchas and Tips

Pitfalls

1. Connection Issues:

   • Ensure the transport (Redis, RabbitMQ, etc.) is running and accessible.
   • Check enqueue.yaml for correct dsn configuration.
   • Debug with:

     php bin/console debug:container enqueue.client
     

2. Job Serialization Failures:

   • Non-serializable objects (e.g., closures, resources) will break jobs.
   • Fix: Use Enqueue\Util\JSON or a custom serializer for complex objects.

3. Consumer Stuck in Loop:

   • Consumers may hang if the transport is down or jobs are unprocessable.
   • Fix: Implement proper error handling and retry logic.

4. Duplicate Job Processing:

   • Without acknowledgment (acknowledge()), jobs may be reprocessed.
   • Fix: Always call acknowledge() after successful processing.

5. Symfony Cache Conflicts:

   • Clear cache after changing enqueue.yaml:

     php bin/console cache:clear
     

Debugging

• Log Producer/Consumer Activity:

  enqueue:
      clients:
          default:
              dsn: 'redis://localhost'
              logger: '@monolog.logger.enqueue'
  

• Inspect Queue:
  • Use Redis CLI or RabbitMQ management UI to verify jobs are enqueued.

Extension Points

1. Custom Transports:

   • Extend Enqueue\Client\Transport\TransportInterface for custom backends (e.g., AWS SQS).

2. Middleware:

   • Add middleware to producers/consumers for logging, metrics, or validation:

     enqueue:
         clients:
             default:
                 middleware:
                     - '@App\Middleware\LoggingMiddleware'
     

3. Dynamic Routing:

   • Route jobs to different queues based on conditions:

     $producer->send(new Job(), 'high_priority_queue');
     

4. Monitoring:

   • Integrate with tools like Prometheus or Datadog via custom metrics middleware.

Configuration Quirks

• Default Client Alias:
  • The default client is auto-configured but can be overridden in enqueue.yaml.
• Environment-Specific Configs:
  • Use %env(resolve: QUEUE_DSN)% for environment variables:

    enqueue:
        clients:
            default:
                dsn: '%env(resolve: QUEUE_DSN)%'