Gearman Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require derrabus/gearman-bundle
   

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

   Derrabus\GearmanBundle\GearmanServiceProvider::class,
   

2. Configuration Publish the config file:

   php artisan vendor:publish --provider="Derrabus\GearmanBundle\GearmanServiceProvider" --tag="config"
   

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

3. First Use Case Dispatch a simple job:

   use Derrabus\GearmanBundle\Gearman;
   
   $gearman = app(Gearman::class);
   $result = $gearman->addJob('test_task', function() {
       return "Hello, Gearman!";
   });
   

Implementation Patterns

Job Dispatching

• Synchronous Jobs Use addJob() for blocking calls:

  $result = $gearman->addJob('process_data', [$data], function($data) {
      return process($data);
  });
  

• Asynchronous Jobs Use addBackgroundJob() for fire-and-forget:

  $gearman->addBackgroundJob('send_email', [$userId, $template]);
  

• Job Groups Dispatch multiple jobs in parallel:

  $jobs = [
      ['task' => 'render_pdf', 'args' => [$orderId]],
      ['task' => 'send_notification', 'args' => [$userId]],
  ];
  $gearman->addJobGroup($jobs);
  

Worker Registration

• Local Workers Register a worker in a Laravel command:

  use Derrabus\GearmanBundle\Worker;
  
  class ProcessOrdersCommand extends Command {
      protected $signature = 'gearman:work';
      public function handle() {
          $worker = new Worker('process_order', function($job) {
              return handleOrder($job->args);
          });
          $worker->run();
      }
  }
  

• Remote Workers Deploy workers on separate servers and point them to the same Gearman server.

Integration with Laravel Queues

• Queue Worker Bridge Use Gearman as a queue driver in .env:

  QUEUE_CONNECTION=gearman
  

  Define the connection in config/queue.php:

  'connections' => [
      'gearman' => [
          'driver' => 'gearman',
          'host' => env('GEARMAN_HOST', 'localhost'),
      ],
  ],
  

• Job Payloads Serialize Laravel jobs for Gearman:

  $gearman->addJob('laravel_job', [
      'job' => serialize($job),
      'data' => $job->resolve(),
  ]);
  

Gotchas and Tips

Configuration Quirks

• Default Timeout Gearman jobs default to no timeout. Set a timeout in the config:

  'default_timeout' => 30, // seconds
  

  Override per job:

  $gearman->addJob('long_task', [], null, 60); // 60-second timeout
  

• Worker Heartbeat Workers may disconnect if idle. Use setOptions() to adjust:

  $worker->setOptions(['heartbeat' => 5]); // 5-second heartbeat
  

Debugging

• Job Failures Check Gearman’s error queue:

  gearman --job-server=localhost:4730 --job-list --job-priority=low
  

  Log worker errors in Laravel:

  try {
      $worker->run();
  } catch (\Exception $e) {
      \Log::error("Gearman worker failed: " . $e->getMessage());
  }
  

• Connection Issues Verify Gearman server is running:

  gearman --version
  

  Test connectivity:

  if (!$gearman->ping()) {
      throw new \RuntimeException("Gearman server unavailable");
  }
  

Extension Points

• Custom Task Handlers Extend the TaskHandler interface for reusable logic:

  class MyTaskHandler implements \Derrabus\GearmanBundle\TaskHandler {
      public function handle($task, $args) {
          // Custom logic
      }
  }
  

• Middleware for Jobs Wrap jobs in middleware (e.g., logging, auth):

  $gearman->addJob('secure_task', [$data], function($args) {
      return app(\App\Services\SecureTaskHandler::class)->handle($args);
  });
  

• Monitoring Integrate with Laravel Horizon or custom TTL:

  $gearman->addJob('monitored_task', [], null, 3600); // 1-hour TTL