Job Queue Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require aureja/job-queue
   

   Publish the config file:

   php artisan vendor:publish --provider="Aureja\JobQueue\JobQueueServiceProvider"
   

2. Configuration: Edit config/job-queue.php to define your queue connections (e.g., database, redis, beanstalk). Example:

   'connections' => [
       'database' => [
           'driver' => 'database',
           'table' => 'job_queue',
           'connection' => 'mysql',
       ],
       'redis' => [
           'driver' => 'redis',
           'connection' => 'cache',
       ],
   ],
   

3. First Use Case: Define a job:

   use Aureja\JobQueue\Contracts\JobInterface;
   
   class SendEmailJob implements JobInterface {
       public function handle() {
           // Your job logic here
       }
   }
   

   Dispatch the job:

   use Aureja\JobQueue\Facades\JobQueue;
   
   JobQueue::dispatch(new SendEmailJob());
   

4. Run the Worker:

   php artisan job:work database --queue=default
   

   (Replace database with your connection name.)

Implementation Patterns

Core Workflows

1. Job Dispatching:

   • Use JobQueue::dispatch() for synchronous dispatching.
   • For delayed jobs, use:

     JobQueue::dispatch(new SendEmailJob())->delay(now()->addMinutes(10));
     

   • Dispatch to a specific queue:

     JobQueue::dispatch(new SendEmailJob())->onQueue('emails');
     

2. Job Processing:

   • Implement JobInterface for custom jobs. The handle() method is executed by the worker.
   • Use middleware for job processing (e.g., logging, retries):

     public function handle() {
         // Job logic
     }
     
     public function middleware() {
         return [
             \Aureja\JobQueue\Middleware\Retry::class,
             \Aureja\JobQueue\Middleware\Log::class,
         ];
     }
     

3. Worker Management:

   • Run workers for specific queues:

     php artisan job:work redis --queue=emails,notifications
     

   • Supervisor setup (example for supervisord.conf):

     [program:laravel-worker]
     command=php /path/to/artisan job:work redis --queue=default
     autostart=true
     autorestart=true
     user=www-data
     numprocs=4
     

4. Batch Processing:

   • Dispatch jobs in batches:

     JobQueue::batch(new SendEmailJob(), 50)->dispatch();
     

   • Process batches with job:batch artisan command.

Integration Tips

• Laravel Events: Dispatch jobs from event listeners:

  public function handle(UserRegistered $event) {
      JobQueue::dispatch(new SendWelcomeEmailJob($event->user));
  }
  

• API Endpoints: Trigger jobs via API:

  Route::post('/send-email', function () {
      JobQueue::dispatch(new SendEmailJob());
      return response()->json(['status' => 'queued']);
  });
  

• Testing: Use JobQueue::fake() in tests:

  public function test_job_is_dispatched() {
      JobQueue::fake();
      JobQueue::dispatch(new SendEmailJob());
  
      JobQueue::assertDispatched(SendEmailJob::class);
  }
  

Gotchas and Tips

Pitfalls

1. Connection Configuration:

   • Ensure your queue connection (e.g., Redis, Database) is properly configured in Laravel. For example, Redis requires the predis/predis package:

     composer require predis/predis
     

   • Database queues require the table to exist. Run migrations if using the built-in database driver:

     php artisan migrate
     

2. Worker Stuck Jobs:

   • If a worker hangs, check for long-running jobs or deadlocks. Use --timeout flag to limit execution time:

     php artisan job:work redis --timeout=60
     

   • Failed jobs may pile up. Monitor with:

     php artisan job:failed
     

3. Middleware Order:

   • Middleware runs in the order defined in middleware(). Place Retry before Log to avoid logging retry attempts:

     public function middleware() {
         return [
             \Aureja\JobQueue\Middleware\Retry::class,
             \Aureja\JobQueue\Middleware\Log::class,
         ];
     }
     

4. Serialization:

   • Jobs with complex objects (e.g., Eloquent models) must be serializable. Use __serialize() and __unserialize():

     public function __serialize() {
         return ['user_id' => $this->user->id];
     }
     
     public function __unserialize(array $data) {
         $this->user = User::find($data['user_id']);
     }
     

Debugging

• Log Output: Enable debug mode in config/job-queue.php:

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

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

• Worker Verbosity: Run workers with -v for verbose output:

  php artisan job:work redis -v
  

• Failed Jobs: Retry or delete failed jobs:

  php artisan job:retry <job_id>
  php artisan job:forget <job_id>
  

Extension Points

1. Custom Drivers: Extend Aureja\JobQueue\Contracts\QueueConnectionInterface to support new backends (e.g., RabbitMQ, AWS SQS).

2. Job Events: Listen for job events (e.g., JobProcessed, JobFailed) via Laravel's event system:

   Event::listen(JobProcessed::class, function ($event) {
       // Handle job completion
   });
   

3. Job Metadata: Attach metadata to jobs for tracking:

   JobQueue::dispatch(new SendEmailJob())->withMetadata(['priority' => 'high']);
   

   Access metadata in handle() via $this->metadata.

4. Queue Monitoring: Build a dashboard using the job:list command or create a custom API endpoint to fetch queue stats:

   Route::get('/queue/stats', function () {
       return JobQueue::stats();
   });