Job Queue Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require cloudone/job-queue-bundle
   

   Register the bundle in config/bundles.php:

   return [
       // ...
       CloudOne\JobQueueBundle\JobQueueBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php artisan vendor:publish --provider="CloudOne\JobQueueBundle\JobQueueServiceProvider"
   

   Edit config/job_queue.php to define your queue connection (e.g., Redis, database, or custom).

3. First Job Create a job class:

   namespace App\Jobs;
   
   use CloudOne\JobQueueBundle\Contracts\JobInterface;
   
   class ProcessOrder implements JobInterface
   {
       public function handle()
       {
           // Your job logic here
       }
   }
   

4. Dispatching a Job

   use App\Jobs\ProcessOrder;
   use CloudOne\JobQueueBundle\Facades\JobQueue;
   
   JobQueue::dispatch(new ProcessOrder());
   

5. Run the Worker

   php artisan job:work
   

Implementation Patterns

Workflow Integration

• Queue Consumption Use the JobQueue facade to dispatch jobs and manage queues:

  // Dispatch with delay
  JobQueue::dispatch(new ProcessOrder(), now()->addMinutes(5));
  
  // Dispatch with priority
  JobQueue::dispatch(new ProcessOrder(), null, 'high');
  

• Job Chaining Chain jobs sequentially or in parallel:

  JobQueue::chain([
      new ProcessOrder(),
      new SendNotification(),
  ]);
  

• Batching Jobs Process multiple jobs in a batch:

  JobQueue::batch([
      new ProcessOrder(1),
      new ProcessOrder(2),
      new ProcessOrder(3),
  ], function ($batch) {
      // Optional batch callback
  });
  

Common Use Cases

• Background Processing Offload time-consuming tasks (e.g., image processing, reports) to the queue.

• Event-Driven Workflows Trigger jobs from Laravel events:

  event(new OrderPlaced($order));
  // In a listener:
  JobQueue::dispatch(new ProcessOrder($order));
  

• Retry Mechanisms Configure retries in config/job_queue.php:

  'retries' => 3,
  'retry_after' => 60, // seconds
  

Integration Tips

• Custom Connections Extend the bundle to support custom queue backends by implementing CloudOne\JobQueueBundle\Contracts\QueueConnectionInterface.

• Middleware Use Laravel’s queue middleware (e.g., throttle, retry) with the bundle’s jobs:

  $job->middleware([new RetryUntil(3)]);
  

• Monitoring Log job execution in a database table (e.g., jobs) for tracking:

  JobQueue::dispatch(new ProcessOrder(), null, 'default', ['log' => true]);
  

Gotchas and Tips

Pitfalls

• Job Serialization Ensure job classes are serializable (avoid closures or non-serializable properties). Use __serialize()/__unserialize() if needed:

  public function __serialize()
  {
      return ['data' => $this->data];
  }
  
  public function __unserialize(array $data)
  {
      $this->data = $data['data'];
  }
  

• Connection Configuration Misconfigured job_queue.php (e.g., wrong Redis host) will cause silent failures. Test connections with:

  php artisan job:test-connection
  

• Worker Stuck on Jobs If workers hang, check for:

  • Unhandled exceptions in handle().
  • Deadlocks in custom queue connections.
  • Use php artisan job:flush to clear stuck jobs (if supported).

Debugging

• Logging Enable debug mode in config/job_queue.php:

  'debug' => env('APP_DEBUG', false),
  

  Logs will appear in storage/logs/job_queue.log.

• Job Inspection List queued jobs:

  php artisan job:list
  

  View job details:

  php artisan job:inspect <job_id>
  

Extension Points

• Custom Job Classes Extend CloudOne\JobQueueBundle\AbstractJob for shared functionality:

  abstract class BaseJob extends AbstractJob
  {
      public function log(string $message)
      {
          \Log::info($message, ['job' => $this->getJobId()]);
      }
  }
  

• Queue Connection Override the default connection by binding your implementation in the service provider:

  $this->app->bind(
      \CloudOne\JobQueueBundle\Contracts\QueueConnectionInterface::class,
      \App\Services\CustomQueueConnection::class
  );
  

• Job Events Listen for job events (e.g., JobStarted, JobFailed) via Laravel’s event system:

  event(new JobStarted($job));
  

Performance Tips

• Batch Processing Use JobQueue::batch() to reduce database/Redis overhead for bulk operations.

• Connection Pooling Reuse queue connections (e.g., Redis) efficiently by configuring timeouts in config/job_queue.php:

  'redis' => [
      'timeout' => 5.0,
      'retry_interval' => 100,
  ],
  

• Avoid Blocking Calls Ensure handle() methods are non-blocking (e.g., use queues for external API calls).