Gearman Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require dmank/gearman-bundle
   

   Add to config/app.php under providers:

   DominikMank\GearmanBundle\GearmanBundle::class,
   

2. Configuration: Edit config/gearman.php to define your Gearman server(s):

   return [
       'servers' => [
           'default' => [
               'host' => '127.0.0.1',
               'port' => 4730,
           ],
       ],
   ];
   

3. First Use Case: Define a job class:

   namespace App\Jobs;
   
   use DominikMank\GearmanBundle\Job\JobInterface;
   
   class ProcessData implements JobInterface
   {
       public function run()
       {
           // Your logic here
           return 'Processed!';
       }
   }
   

   Dispatch the job:

   $client = app('gearman.client');
   $client->addJob('process_data', new ProcessData(), function ($job) {
       // Handle response
   });
   

Implementation Patterns

Common Workflows

1. Job Dispatching:

   // Basic dispatch
   $client->addJob('task_name', new MyJob(), function ($job) {});
   
   // With unique ID
   $client->addJob('task_name', new MyJob(), function ($job) {}, 'unique_id');
   
   // With priority
   $client->addJob('task_name', new MyJob(), function ($job) {}, null, 1000);
   

2. Background Jobs: Use addBackgroundJob() for fire-and-forget tasks:

   $client->addBackgroundJob('task_name', new MyJob());
   

3. Integration with Laravel Queues: Create a custom queue driver:

   // config/queue.php
   'connections' => [
       'gearman' => [
           'driver' => 'gearman',
           'server' => 'default',
       ],
   ],
   

   Dispatch via Laravel’s queue system:

   dispatch(new MyJob());
   

4. Worker Setup: Register a worker in app/Console/Kernel.php:

   protected function schedule(Schedule $schedule)
   {
       $schedule->command('gearman:work')->everyMinute();
   }
   

   Run workers:

   php artisan gearman:work
   

5. Task Groups: Use addTask() for grouped jobs:

   $group = $client->addTask();
   $group->addJob('task1', new Job1());
   $group->addJob('task2', new Job2());
   $group->run();
   

Gotchas and Tips

Pitfalls

1. Connection Issues:

   • Gearman servers may be unreachable. Handle exceptions:

     try {
         $client->addJob(...);
     } catch (\GearmanException $e) {
         Log::error('Gearman error: ' . $e->getMessage());
     }
     

   • Use ping() to check server connectivity:

     $client->ping();
     

2. Job Timeouts:

   • Default timeout is 30 seconds. Adjust in config/gearman.php:

     'timeout' => 60, // seconds
     

   • Long-running jobs may fail silently; consider breaking them into smaller tasks.

3. Worker Stuck on Tasks:

   • Workers may hang if tasks throw unhandled exceptions. Implement onException() in jobs:

     public function onException(\Exception $e)
     {
         Log::error('Job failed: ' . $e->getMessage());
     }
     

4. Serialization:

   • Job arguments must be serializable. Avoid passing non-serializable objects (e.g., closures, resources).
   • Use __serialize() and __unserialize() in jobs for complex data:

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

Tips

1. Logging: Enable debug logging in config/gearman.php:

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

   Log worker activity:

   $client->setLogger(function ($message) {
       Log::debug($message);
   });
   

2. Testing: Use GearmanMock for unit tests:

   $mock = new \DominikMank\GearmanBundle\Testing\GearmanMock();
   $client = new \GearmanClient();
   $client->addServer($mock);
   

3. Load Balancing: Configure multiple servers for redundancy:

   'servers' => [
       'primary' => ['host' => '127.0.0.1', 'port' => 4730],
       'backup' => ['host' => '192.168.1.100', 'port' => 4730],
   ],
   

   Use setServers() dynamically:

   $client->setServers(['primary', 'backup']);
   

4. Monitoring: Track job progress with callbacks:

   $client->addJob('task', new MyJob(), function ($job) {
       Log::info('Job progress: ' . $job->getProgress());
   });
   

5. Custom Workers: Extend \DominikMank\GearmanBundle\Worker\Worker for custom logic:

   class MyWorker extends Worker
   {
       protected function getTasks()
       {
           return ['task1', 'task2'];
       }
   }
   

   Register in services.yaml:

   gearman.worker.class: App\Worker\MyWorker