Gearman Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require eduardtrandafir/gearman-bundle
   

   Register the bundle in config/app.php under providers:

   EduardTrandafir\GmBundle\GmBundle::class,
   

2. Configuration Publish the default config:

   php artisan vendor:publish --provider="EduardTrandafir\GmBundle\GmBundle" --tag=config
   

   Update config/gm.php with your Gearman server details (host, port, etc.).

3. First Use Case Define a simple job task:

   use EduardTrandafir\GmBundle\Task\TaskInterface;
   
   class ExampleTask implements TaskInterface
   {
       public function run($workload)
       {
           return "Processed: " . $workload;
       }
   }
   

   Register the task in config/gm.php:

   'tasks' => [
       'example_task' => [
           'class' => \App\Jobs\ExampleTask::class,
           'timeout' => 30,
       ],
   ],
   

   Dispatch the job:

   $client = app('gearman.client');
   $client->addTask('example_task', 'Hello Gearman!');
   

Implementation Patterns

Workflow Integration

1. Job Dispatching Use the Gearman client to offload CPU-intensive tasks:

   $client = app('gearman.client');
   $client->addTask('image_processing', $imageData, function($task) {
       // Optional callback for task completion
       return $task->data();
   });
   

2. Worker Management Register workers in config/gm.php:

   'workers' => [
       'image_processor' => [
           'class' => \App\Workers\ImageProcessor::class,
           'tasks' => ['image_processing'],
           'options' => ['timeout' => 60],
       ],
   ],
   

   Start workers via Artisan command:

   php artisan gm:worker image_processor
   

3. Task Chaining Chain tasks for sequential processing:

   $client->addTask('task_one', $data, function($task) {
       return $task->data() . "_processed";
   })->addTask('task_two', $task->data());
   

4. Background Processing Use Laravel’s queue system to trigger Gearman jobs:

   Dispatch::onQueue('gearman')->dispatch(new ProcessDataJob($data));
   

Common Patterns

• Error Handling: Implement TaskInterface::run() to return false or throw exceptions for failed tasks.
• Data Serialization: Ensure payloads are JSON-serializable (use json_encode()/json_decode()).
• Task Prioritization: Use Gearman’s job priority flags (e.g., GearmanWorker::addOptions(GEARMAN_WORKER_NICE)).

Gotchas and Tips

Pitfalls

1. Worker Registration

   • Issue: Workers must be registered in config/gm.php and started via php artisan gm:worker.
   • Fix: Verify the worker command is in your app/Console/Kernel.php schedule or run manually.

2. Task Timeouts

   • Issue: Default timeouts (e.g., 30s) may be too short for long-running tasks.
   • Fix: Adjust timeout in config/gm.php or worker options:

     'options' => ['timeout' => 300], // 5 minutes
     

3. Data Corruption

   • Issue: Non-serializable data (e.g., objects, resources) will break tasks.
   • Fix: Use json_encode() for payloads or implement __serialize()/__unserialize().

4. Connection Issues

   • Issue: Gearman server downtime or misconfigured host/port.
   • Fix: Add retry logic or use Laravel’s retry helper:

     try {
         $client->addTask('task', $data);
     } catch (\Exception $e) {
         retry()->times(3)->later(5)->try(fn() => $client->addTask('task', $data));
     }
     

Debugging Tips

• Logs: Enable Gearman worker logs in config/gm.php:

  'log' => [
      'level' => 'debug',
      'file' => storage_path('logs/gearman.log'),
  ],
  

• Task Inspection: Use php artisan gm:status to check pending/running tasks.
• Worker Isolation: Run workers in separate processes/servers to avoid resource contention.

Extension Points

1. Custom Workers Extend EduardTrandafir\GmBundle\Worker\AbstractWorker for reusable worker logic:

   class CustomWorker extends AbstractWorker
   {
       protected function handleTask($task)
       {
           // Custom logic
       }
   }
   

2. Task Middleware Add middleware to tasks via TaskInterface:

   public function run($workload)
   {
       $this->middleware->preProcess($workload);
       $result = $this->process($workload);
       return $this->middleware->postProcess($result);
   }
   

3. Event Listeners Listen for task events (e.g., TaskStarted, TaskCompleted) via Laravel’s event system:

   Event::listen('gearman.task.completed', function($event) {
       Log::info("Task {$event->taskName} completed");
   });
   

4. Monitoring Integrate with Laravel Horizon or custom dashboards by exposing Gearman stats via:

   $client->stats(); // Returns server/worker statistics