Gearman Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require dmank/gearman:@stable
   

2. Basic Client Initialization:

   use dmank\gearman\Server;
   use dmank\gearman\ServerCollection;
   use dmank\gearman\Client;
   
   $server = new Server('localhost', 4730); // Default Gearman server
   $serverCollection = new ServerCollection();
   $serverCollection->add($server);
   $client = new Client($serverCollection);
   

3. First Use Case: Dispatch a simple async job:

   $jobHandle = $client->executeInBackground('process_data', ['data' => 'test']);
   

Key Files to Review

• src/Client.php – Core client logic for job dispatching.
• src/Server.php – Server connection configuration.
• src/ServerCollection.php – Load balancing across multiple Gearman servers.

Implementation Patterns

Workflow: Job Dispatching

1. Async Jobs:

   $client->executeInBackground('task_name', $workload, [
       'unique' => true, // Prevent duplicate jobs
       'priority' => 100, // Adjust priority (0-255)
       'timeout' => 30, // Seconds before timeout
   ]);
   

   • Use executeInBackground for fire-and-forget tasks (e.g., image resizing, PDF generation).
   • Store $jobHandle to track progress later.

2. Sync Jobs:

   $result = $client->executeJob('task_name', $workload);
   

   • Use executeJob for blocking tasks (e.g., validation, critical data processing).
   • Handle exceptions with try-catch (e.g., GearmanException).

3. Worker Registration:

   use dmank\gearman\Worker;
   
   $worker = new Worker('localhost', 4730);
   $worker->addTask('task_name', function ($job) {
       return $job->run(); // Process workload
   });
   $worker->run();
   

   • Register workers in Laravel’s boot() (e.g., AppServiceProvider) for long-running tasks.
   • Use addTask() to map job names to closures or class methods.

Integration with Laravel

1. Service Provider: Bind the client to the container:

   public function register()
   {
       $this->app->singleton('gearman.client', function ($app) {
           $server = new Server(config('gearman.host'));
           $collection = new ServerCollection();
           $collection->add($server);
           return new Client($collection);
       });
   }
   

2. Job Queues: Dispatch jobs via a facade or helper:

   // config/gearman.php
   return [
       'host' => 'localhost',
       'port' => 4730,
   ];
   
   // app/Helpers/Gearman.php
   function dispatch($jobName, $data, $options = [])
   {
       return app('gearman.client')->executeInBackground($jobName, $data, $options);
   }
   

3. Worker Management: Run workers via Artisan commands:

   // app/Console/Commands/RunGearmanWorker.php
   public function handle()
   {
       $worker = new Worker(config('gearman.host'));
       $worker->addTask('email.send', [EmailSender::class, 'send']);
       $worker->run();
   }
   

Gotchas and Tips

Pitfalls

1. Connection Issues:

   • Gearman servers may drop connections. Use ServerCollection to distribute jobs across multiple servers.
   • Fix: Implement retry logic in the client:

     try {
         $client->executeInBackground('task', $data);
     } catch (\dmank\gearman\GearmanException $e) {
         if ($e->getCode() === 1) { // Gearman::FAILURE
             sleep(2);
             retry();
         }
     }
     

2. Worker Crashes:

   • Workers die silently if uncaught exceptions occur. Wrap task logic in try-catch:

     $worker->addTask('task', function ($job) {
         try {
             return $job->run();
         } catch (\Exception $e) {
             \Log::error("Worker failed: " . $e->getMessage());
             throw $e; // Re-throw to mark job as failed
         }
     });
     

3. Timeouts:

   • Default timeout is 30 seconds. Adjust via $client->setTimeout(60) or per-job:

     $client->executeInBackground('task', $data, ['timeout' => 120]);
     

4. Duplicate Jobs:

   • Async jobs may run multiple times if not marked as unique:

     $client->executeInBackground('task', $data, ['unique' => true]);
     

Debugging

1. Enable Gearman Logging: Set the log file path in Server:

   $server = new Server('localhost', 4730, '/path/to/gearman.log');
   

2. Check Job Status: Use executeJobStatus to inspect async jobs:

   $status = $client->executeJobStatus($jobHandle);
   if ($status->getState() === \dmank\gearman\JobStatus::COMPLETE) {
       $result = $status->getData();
   }
   

3. Monitor Workers: Use gearman-worker --log-level=debug to debug worker processes.

Extension Points

1. Custom Job Classes: Extend dmank\gearman\Job to add metadata or pre/post-processing:

   class CustomJob extends \dmank\gearman\Job
   {
       public function __construct($workload)
       {
           parent::__construct($workload);
           $this->setPriority(200); // High priority
       }
   }
   

2. Middleware for Workers: Add cross-cutting logic (e.g., logging, auth) via closures:

   $worker->addTask('task', function ($job) {
       \Log::info("Processing job ID: " . $job->getUnique());
       return $job->run();
   });
   

3. Fallback Mechanisms: Combine with Laravel queues for redundancy:

   if (config('gearman.enabled')) {
       $client->executeInBackground('task', $data);
   } else {
       dispatch(new FallbackJob($data));
   }
   

Configuration Quirks

1. Server Collection Order: Jobs are dispatched to the first available server in the collection. Shuffle servers for load balancing:

   $servers = [
       new Server('server1', 4730),
       new Server('server2', 4730),
   ];
   shuffle($servers);
   $serverCollection->addMultiple($servers);
   

2. PHP Gearman Extension: The package relies on the php-gearman extension. Ensure it’s installed:

   pecl install gearman
   

   Add to php.ini:

   extension=gearman.so
   

3. Job Data Serialization: Workloads are serialized via PHP’s serialize(). For complex objects, implement __serialize()/__unserialize() or use JSON:

   $client->executeInBackground('task', json_encode($data));