Yii2 Queue Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require yiisoft/yii2-queue
   

   Add to your config/web.php or config/console.php:

   'components' => [
       'queue' => [
           'class' => 'yiisoft\queue\Queue',
           'connections' => [
               'db' => [
                   'class' => 'yiisoft\queue\db\Queue',
                   'tableName' => '{{%queue_job}}',
               ],
           ],
       ],
   ],
   

2. Create a Job

   php yii queue/create-job SendWelcomeEmail
   

   This generates a job class in jobs/SendWelcomeEmail.php:

   namespace app\jobs;
   
   use yii\queue\JobInterface;
   
   class SendWelcomeEmail implements JobInterface {
       public $userId;
   
       public function execute($queue, $data) {
           // Logic to send email
       }
   }
   

3. Run a Worker

   php yii queue/run db --queue=default --delay=1
   

First Use Case

Dispatch a job immediately:

Yii::$app->queue->push(new SendWelcomeEmail(['userId' => 123]));

Implementation Patterns

Workflow: Job Dispatching

1. Delayed Jobs

   Yii::$app->queue->push(new SendWelcomeEmail(['userId' => 123]))
       ->delay(3600); // Delay for 1 hour
   

2. Retry Logic

   Yii::$app->queue->push(new SendWelcomeEmail(['userId' => 123]))
       ->retry(3, 60); // Retry 3 times, every 60 seconds
   

3. Queue-Specific Dispatching

   Yii::$app->queue->push(new SendWelcomeEmail(['userId' => 123]))
       ->queue('high_priority');
   

Integration Tips

• Database Queue: Useful for small-scale apps or when Redis/RabbitMQ isn’t available. Ensure tableName is properly configured.
• Redis Queue: Ideal for high-throughput systems. Configure with:

  'redis' => [
      'class' => 'yiisoft\queue\redis\Queue',
      'dsn' => 'redis://localhost:6379',
  ],
  

• RabbitMQ Queue: Best for distributed systems. Configure with:

  'rabbitmq' => [
      'class' => 'yiisoft\queue\rabbitmq\Queue',
      'dsn' => 'amqp://guest:guest@localhost:5672',
  ],
  

• Job Chaining: Dispatch jobs sequentially or in parallel:

  Yii::$app->queue->push(new ProcessOrder(['orderId' => 1]))
      ->then(new SendOrderConfirmation(['orderId' => 1]));
  

Worker Management

• Daemon Mode: Run workers in the background:

  php yii queue/run db --daemon --queue=default
  

• Monitoring: Use --log-level=debug for detailed logs or integrate with yii\monolog\Target\FileTarget for persistent logging.

Gotchas and Tips

Pitfalls

1. Database Locking: DB queues use FOR UPDATE locks. Long-running jobs may block other jobs. Avoid heavy operations in jobs.
2. Connection Failures: Redis/RabbitMQ workers may fail silently if the connection drops. Implement health checks or use yiisoft\queue\ConnectionEvent to handle disconnections.
3. Job Serialization: Only serializable data (arrays, simple objects) can be passed to jobs. Avoid passing closures or non-serializable objects.
4. Timeouts: Workers have a default timeout (30 seconds for DB, configurable for others). Adjust based on job complexity:

   Yii::$app->queue->push(new LongRunningJob())->timeout(300); // 5 minutes
   

Debugging

• Job Stuck in Queue: Check the failed_jobs table (DB) or Redis keys for stuck jobs. Manually delete or retry:

  php yii queue/retry-all db --queue=default
  

• Worker Not Processing: Verify the queue connection is alive and the worker has access to the queue. Use --log-level=debug to diagnose.
• Job Failing Silently: Implement a yiisoft\queue\JobEvent listener to log failures:

  Yii::$app->queue->on(JobEvent::EVENT_FAILED, function ($event) {
      Yii::error("Job failed: " . $event->job->getClass());
  });
  

Configuration Quirks

1. Table Naming: For DB queues, ensure the table exists and matches the tableName config. Run migrations if needed.
2. Redis Prefix: Redis queues use a default prefix (queue_). Customize with:

   'redis' => [
       'prefix' => 'custom_queue_',
   ],
   

3. RabbitMQ Exchanges: RabbitMQ queues require explicit exchange declarations. Configure in the connection:

   'rabbitmq' => [
       'exchange' => 'my_exchange',
       'exchangeType' => 'direct',
   ],
   

Extension Points

1. Custom Job Classes: Extend yiisoft\queue\Job for shared functionality:

   class BaseJob extends \yiisoft\queue\Job {
       public function getRetryDelay() {
           return 60; // Default retry delay
       }
   }
   

2. Middleware: Add middleware to jobs for logging, retries, or metrics:

   Yii::$app->queue->push(new MyJob())->middleware([
       new \yiisoft\queue\middleware\Retry(),
       new \app\middleware\LogJobExecution(),
   ]);
   

3. Event Handling: Listen to queue events for monitoring or custom logic:

   Yii::$app->queue->on(QueueEvent::EVENT_BEFORE_PUSH, function ($event) {
       // Pre-process job data
   });