Worker Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require acassan/worker-bundle
   php artisan vendor:publish --provider="Acassan\WorkerBundle\WorkerBundle" --tag=config
   

   Publish the default config and migrations if needed.

2. Configure Queue Connection Edit config/worker.php to specify your queue connection (e.g., database, redis, beanstalk):

   'connection' => env('QUEUE_CONNECTION', 'database'),
   

3. Define a Worker Job Create a job class extending Acassan\WorkerBundle\Contracts\WorkerJob:

   namespace App\Jobs;
   
   use Acassan\WorkerBundle\Contracts\WorkerJob;
   
   class ProcessData implements WorkerJob
   {
       public function handle()
       {
           // Your job logic here
           return true; // Return true for success, false for failure
       }
   }
   

4. Dispatch a Job

   use App\Jobs\ProcessData;
   
   ProcessData::dispatch();
   

5. Run the Worker

   php artisan worker:run
   

   Or use the Tinker console for testing:

   php artisan tinker
   Worker::run();
   

First Use Case

Use the bundle to offload a time-consuming task (e.g., processing CSV files) by dispatching a job and letting the worker handle it asynchronously.

Implementation Patterns

Workflow: Job Dispatch and Processing

1. Dispatch Jobs

   // Dispatch with payload
   ProcessData::dispatch(['data' => $payload]);
   
   // Dispatch with delay (in seconds)
   ProcessData::dispatch()->delay(60);
   

2. Worker Management

   • Run Workers: Start workers via CLI (php artisan worker:run) or programmatically.
   • Worker Pooling: Configure the number of workers in config/worker.php:

     'workers' => [
         'max_processes' => 4, // Default: 1
         'timeout' => 60,       // Default: 60 (seconds)
     ],
     

   • Graceful Shutdown: Use Worker::stop() to halt workers cleanly.

3. Job Retries Configure retries in config/worker.php:

   'retries' => 3,
   'retry_delay' => 10, // Seconds between retries
   

4. Monitoring

   • Log job execution in handle():

     \Log::info('Processing data', ['data' => $this->data]);
     

   • Use Laravel’s queue tables (jobs) to track job status.

Integration Tips

• Queue Events: Listen to JobProcessed and JobFailed events for post-processing:

  event(new JobProcessed($job));
  

• Custom Middleware: Extend Acassan\WorkerBundle\Middleware\WorkerMiddleware to add pre/post-processing logic.
• Testing: Use Worker::fake() in tests to simulate job processing:

  $this->fake(Worker::class);
  ProcessData::dispatch();
  $this->assertProcessed();
  

Gotchas and Tips

Pitfalls

1. Connection Issues

   • Ensure your queue connection (e.g., Redis, Database) is properly configured in .env.
   • Debug with:

     php artisan queue:failed-table  # Check failed jobs
     php artisan queue:work --once  # Test manually
     

2. Worker Stuck in Loop

   • If workers hang, check for infinite loops in handle() or deadlocks in database transactions.
   • Set a low timeout in config to force restarts:

     'timeout' => 30,
     

3. Payload Size Limits

   • Large payloads may cause serialization issues. Use serialize()/unserialize() for complex data or store references in the database.

4. Missing Dependencies

   • Ensure required PHP extensions (e.g., pdo, mbstring) are installed for database/Redis queues.

Debugging Tips

• Log Worker Output: Redirect worker logs to a file:

  php artisan worker:run >> /var/log/worker.log 2>&1
  

• Xdebug: Attach Xdebug to a worker process for step-through debugging:

  # config/worker.php
  'xdebug' => env('APP_DEBUG', false),
  

• Job Dump: Inspect job payloads with:

  \Log::debug('Job data', ['payload' => $this->data]);
  

Extension Points

1. Custom Worker Classes Extend Acassan\WorkerBundle\Worker to add features like:

   • Dynamic worker scaling.
   • Priority queues.

   namespace App\Workers;
   
   use Acassan\WorkerBundle\Worker;
   
   class CustomWorker extends Worker
   {
       protected function getQueue(): string
       {
           return 'custom_queue';
       }
   }
   

2. Job Middleware Register middleware in config/worker.php:

   'middleware' => [
       \App\Middleware\LogJob::class,
   ],
   

3. Event Listeners Listen for worker lifecycle events:

   // EventServiceProvider
   protected $listen = [
       'Acassan\WorkerBundle\Events\WorkerStarted' => [
          \App\Listeners\LogWorkerStart::class,
       ],
   ];
   

4. Queue Table Customization Publish and modify migrations:

   php artisan vendor:publish --tag=worker-migrations