Gearman Bundle Laravel Package

Getting Started

Minimal Setup

1. Install Dependencies Ensure Gearman and PHP PECL extension are installed:

   sudo apt-get install gearman gearman-job-server
   pecl install gearman
   

   Add extension=gearman.so to your php.ini.

2. Composer Install

   composer require cimus/gearman-bundle:dev-master
   

3. Configure Bundle Add to AppKernel.php:

   new Cimus\GearmanBundle\CimusGearmanBundle(),
   

   Configure in config.yml:

   cimus_gearman:
       servers:
           localhost:
               host: 127.0.0.1
               port: 4730
   

4. First Job Submission Inject the Cimus\GearmanBundle\Manager\GearmanManager service and submit a job:

   use Cimus\GearmanBundle\Manager\GearmanManager;
   
   class MyController extends Controller
   {
       public function submitJob(GearmanManager $gearman)
       {
           $gearman->addJob('my_task', function() {
               return "Task completed!";
           });
       }
   }
   

5. Run a Worker Start a worker via CLI:

   php app/console cimus:gearman:worker --task=my_task
   

Implementation Patterns

Job Submission Workflows

1. Synchronous Jobs Use for immediate, blocking tasks:

   $result = $gearman->addJob('sync_task', function() {
       return "Sync result";
   })->run();
   

2. Asynchronous Jobs Fire-and-forget pattern:

   $gearman->addJob('async_task', function() {
       // Background processing
   });
   

3. Task-Specific Workers Register workers for specific tasks in services.yml:

   services:
       my_worker:
           class: AppBundle\Worker\MyWorker
           tags:
               - { name: cimus_gearman.worker, task: my_task }
   

4. Job Dependencies Chain jobs by returning job handles:

   $job1 = $gearman->addJob('task1', function() { return "Step 1"; });
   $job2 = $gearman->addJob('task2', function() use ($job1) {
       return $job1->run() . " + Step 2";
   });
   

Worker Management

1. Dynamic Worker Scaling Use the cimus:gearman:workers command to start multiple workers:

   php app/console cimus:gearman:workers --task=my_task --count=4
   

2. Worker Monitoring Check worker status via:

   php app/console cimus:gearman:monitor
   

3. Worker Lifecycle Implement Cimus\GearmanBundle\Worker\WorkerInterface for custom logic:

   class MyWorker implements WorkerInterface
   {
       public function run($task, $workload)
       {
           // Custom logic
       }
   }
   

Integration Tips

1. Symfony Event Dispatcher Trigger events before/after job execution:

   $gearman->addJob('event_task', function() {
       $this->get('event_dispatcher')->dispatch('task.started');
       return "Done";
   });
   

2. Doctrine Integration Use jobs for batch processing:

   $gearman->addJob('batch_process', function() {
       $em = $this->get('doctrine')->getManager();
       // Bulk operations
   });
   

3. Logging Log job execution in workers:

   class MyWorker implements WorkerInterface
   {
       public function run($task, $workload)
       {
           $this->get('logger')->info("Processing $task");
       }
   }
   

Gotchas and Tips

Pitfalls

1. Worker Registration

   • Issue: Workers not picked up by the bundle.
   • Fix: Ensure workers are tagged correctly in services.yml and the bundle is compiled:

     php app/console cache:clear
     

2. Job Serialization

   • Issue: Complex objects fail to serialize.
   • Fix: Use __serialize()/__unserialize() or pass scalar data.

3. Gearman Server Connection

   • Issue: Jobs hang or fail silently.
   • Fix: Verify Gearman server is running (gearman-job-server) and ports are open.

4. Worker Isolation

   • Issue: Workers share state unexpectedly.
   • Fix: Avoid static variables; use dependency injection for shared resources.

5. Task Naming Collisions

   • Issue: Multiple workers for the same task cause race conditions.
   • Fix: Use unique task names or implement task-specific logic in workers.

Debugging

1. Job Status Check job status via Gearman CLI:

   gearman --status
   

2. Worker Logs Redirect worker output to a file:

   php app/console cimus:gearman:worker --task=my_task >> worker.log 2>&1
   

3. Bundle Debugging Enable debug mode in config.yml:

   cimus_gearman:
       debug: true
   

Configuration Quirks

1. Multiple Servers Configure multiple Gearman servers:

   cimus_gearman:
       servers:
           server1:
               host: 127.0.0.1
               port: 4730
           server2:
               host: 192.168.1.100
               port: 4730
   

   Use setServer() on the manager to switch contexts.

2. Default Task Set a default task for workers:

   cimus_gearman:
       default_task: default_worker
   

Extension Points

1. Custom Job Classes Extend Cimus\GearmanBundle\Job\Job for reusable job logic:

   class EmailJob extends Job
   {
       protected $email;
       public function __construct($email) { $this->email = $email; }
       public function run() { /* ... */ }
   }
   

2. Worker Factories Dynamically create workers based on conditions:

   $worker = $this->get('cimus_gearman.worker_factory')->create('dynamic_task');
   

3. Middleware for Jobs Add preprocessing/postprocessing:

   $gearman->addJob('middleware_task', function() {
       $this->get('my.middleware')->preProcess();
       return "Result";
   })->addPostProcess(function($result) {
       $this->get('my.middleware')->postProcess($result);
   });
   

4. Custom Gearman Clients Override the default client for advanced use cases:

   services:
       my_gearman.client:
           class: GearmanClient
           calls:
               - [setCompleteCallback, ["@my.callback"]]