Pheanstalk 5.3 Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require mrpoundsign/pheanstalk-5.3
   

   Ensure your composer.json has "minimum-stability": "dev" if using this fork.

2. Basic Connection

   $pheanstalk = new \Pheanstalk\Pheanstalk('127.0.0.1', 11300);
   

3. First Use Case: Job Producer

   $pheanstalk->useTube('critical-jobs')->put('Process user upload');
   

4. First Use Case: Job Worker

   $job = $pheanstalk->watch('critical-jobs')->reserve(1); // Timeout in seconds
   if ($job) {
       $data = $job->getData();
       $pheanstalk->delete($job);
   }
   

Where to Look First

• README.md: Focus on the "Usage Example" section for core workflows.
• Protocol Docs: Beanstalkd Protocol for edge cases.
• Tests: tests/ directory for real-world usage patterns (run with ./tests/runtests.php).

Implementation Patterns

Core Workflows

1. Producer Pattern

   $pheanstalk->useTube('emails')->put('Send welcome email', 0, 60, 1024, ['priority' => 1000]);
   

   • Tubes: Use useTube() to scope jobs (e.g., high-priority, low-priority).
   • Delays: Set delay (seconds) for scheduled jobs.
   • TTL: Set timeout (seconds) for job expiration.

2. Worker Pattern

   $pheanstalk->watch('emails')->ignore('default');
   while ($job = $pheanstalk->reserve()) {
       try {
           process($job->getData());
           $pheanstalk->delete($job);
       } catch (\Exception $e) {
           $pheanstalk->release($job); // Retry later
       }
   }
   

   • Watch/Ignore: Balance load across tubes with watch()/ignore().
   • Error Handling: Use release() for retries or bury() for dead-letter queues.

3. Batching Jobs

   $batch = $pheanstalk->batch();
   foreach ($users as $user) {
       $batch->put("Process user {$user['id']}");
   }
   $batch->send();
   

Integration Tips

• Laravel Service Provider

  $this->app->singleton(\Pheanstalk\Pheanstalk::class, function ($app) {
      return new \Pheanstalk\Pheanstalk(config('queue.connection.beanstalk.host'));
  });
  

  Bind to Laravel’s container for dependency injection.

• Job Serialization Use json_encode() for complex payloads:

  $pheanstalk->put(json_encode(['user_id' => 123, 'action' => 'export']));
  

• Connection Pooling Reuse $pheanstalk instances across requests (thread-safe for PHP-FPM).

Gotchas and Tips

Pitfalls

1. Connection Timeouts

   • Beanstalkd defaults to 30-second timeouts. Adjust with:

     $pheanstalk->setReadTimeout(5); // Seconds
     $pheanstalk->setWriteTimeout(5);
     

2. Job Bursting

   • Avoid reserve() loops without delays to prevent CPU overload:

     $job = $pheanstalk->reserve(0.5); // 500ms timeout
     

3. Memory Leaks

   • Unbound tubes persist. Explicitly ignore() unused tubes:

     $pheanstalk->ignore('unwatched-tube');
     

4. PHP 5.3 Legacy

   • No namespaces in original code; this fork adds them. Ensure your IDE recognizes:

     use \Pheanstalk\Pheanstalk; // Explicit namespace
     

Debugging

• Enable Logging

  $pheanstalk->setLogger(new \Monolog\Logger('beanstalk'));
  

• Check Server Status

  $stats = $pheanstalk->stats();
  $tubeStats = $pheanstalk->statsTube('testtube');
  

Extension Points

1. Custom Job Classes Extend \Pheanstalk\Job for metadata:

   class MyJob extends \Pheanstalk\Job {
       public function getUserId() {
           return json_decode($this->getData(), true)['user_id'];
       }
   }
   

2. Middleware Pipeline Intercept jobs before processing:

   $job = $pheanstalk->reserve();
   if ($this->middleware->handle($job)) {
       $pheanstalk->delete($job);
   }
   

3. Retry Logic Implement exponential backoff for failed jobs:

   $attempts = $job->getData()['attempts'] ?? 0;
   if ($attempts > 3) {
       $pheanstalk->bury($job);
   } else {
       $pheanstalk->release($job, 2 ** $attempts); // Delay in seconds
   }
   

Config Quirks

• Default Tube: Jobs go to default tube if no tube is set.
• Priority Ranges: Valid priorities are 0 (lowest) to 4294967295 (highest).
• Binary Data: Use base64_encode() for binary payloads (Beanstalkd is text-only).