Getting Started

Minimal Setup for Laravel

Install Dependencies:

composer require enqueue/pheanstalk pda/pheanstalk enqueue/serializer

Configure Beanstalkd Connection: Add to config/queue.php under connections:

'beanstalkd' => [
    'driver' => 'enqueue',
    'connection' => 'beanstalkd',
    'queue' => 'default',
    'options' => [
        'connection' => [
            'host' => env('BEANSTALKD_HOST', '127.0.0.1'),
            'port' => env('BEANSTALKD_PORT', 11300),
            'timeout' => 5.0,
        ],
        'serializer' => 'enqueue.serializer',
    ],
],

Dispatch a Job:

use App\Jobs\ProcessOrder;
dispatch(new ProcessOrder($orderId))->onConnection('beanstalkd');

Run Worker:

php artisan queue:work --queue=default

Note: For Enqueue consumers, use:

vendor/bin/enqueue consume beanstalkd --queue=default

First Use Case: Async Email Sending

// Dispatch job
dispatch(new SendWelcomeEmail($user))->onConnection('beanstalkd');

// Job class
class SendWelcomeEmail implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue;

    public $user;

    public function handle()
    {
        Mail::to($this->user->email)->send(new WelcomeEmail($this->user));
    }
}

Implementation Patterns

Workflow: Laravel + Enqueue + Beanstalkd

Job Dispatch:

Use Laravel’s dispatch() with onConnection('beanstalkd').

Example:

dispatch(new GenerateReportJob($params))->onConnection('beanstalkd')->delay(now()->addMinutes(5));

Consumer Setup:

Replace queue:work with Enqueue’s consumer:

vendor/bin/enqueue consume beanstalkd --queue=default --memory-limit=128M

For multiple queues:

vendor/bin/enqueue consume beanstalkd --queue=high,default,low

Delayed Jobs:
- Leverage Beanstalkd’s put with delay:
```
dispatch(new Job())->delay(30); // 30 seconds
```

Priority Queues:

Use Beanstalkd’s tubes (queues) with priority:

// Dispatch to a high-priority tube
dispatch(new Job())->onQueue('high-priority');

Configure tubes in config/queue.php:

'beanstalkd' => [
    'connection' => 'beanstalkd',
    'queue' => 'high-priority', // Default tube
],

Integration Tips

Middleware for Jobs: Use Laravel’s HandleJobsMiddleware or Enqueue’s middleware:

use Enqueue\Middleware\Middleware;

$middleware = new Middleware();
$middleware->add(new RetryMiddleware());
$middleware->add(new LoggingMiddleware());

Batch Processing: Use enqueue/batch to group jobs:

$batch = new Batch();
foreach ($orders as $order) {
    $batch->add(new ProcessOrderJob($order));
}
dispatch($batch)->onConnection('beanstalkd');

Monitoring: Integrate with enqueue/doctrine for job tracking or use Beanstalkd’s stats:
```
beanstalkd-console -z
```

Gotchas and Tips

Pitfalls

Serialization Issues:
- Laravel jobs with closures or non-serializable objects (e.g., resources) will fail.
- Fix: Use enqueue/serializer with json or igbinary:
```
'options' => [
    'serializer' => 'enqueue.serializer.json',
],
```
Beanstalkd Restarts:
- In-memory queue means jobs are lost on restart. Use a fallback (e.g., database) for critical jobs.
- Fix: Implement a dead-letter queue (DLQ) with enqueue/delayed:
```
$context = new Context();
$context->setDelay(60); // Retry after 60 seconds
$context->setTtr(300);  // Time-to-run: 5 minutes
$producer->send($message, $context);
```

Connection Timeouts:

Beanstalkd may drop idle connections. Configure timeouts in config/queue.php:

'options' => [
    'connection' => [
        'timeout' => 10.0,
        'read_timeout' => 5.0,
    ],
],

Laravel Queue Facade Limitation:
- The Queue facade may not fully support Enqueue’s features (e.g., priority tubes). Use raw Enqueue methods when needed:
```
use Enqueue\Client\ProducerInterface;
$producer = app(ProducerInterface::class);
$producer->send(new Message('data'));
```

Debugging

Check Beanstalkd Stats:
```
beanstalkd-console -z
```
Look for stalled jobs or tube sizes.

Enable Enqueue Logging: Add to config/logging.php:

'channels' => [
    'enqueue' => [
        'driver' => 'single',
        'path' => storage_path('logs/enqueue.log'),
        'level' => 'debug',
    ],
],

Test Locally: Use Docker for Beanstalkd:

docker run -p 11300:11300 schickling/beanstalkd

Extension Points

Custom Serializer: Extend Enqueue\Serializer\SerializerInterface for Laravel-specific payloads:

class LaravelJobSerializer implements SerializerInterface
{
    public function serialize($data): string
    {
        return serialize($data);
    }

    public function unserialize(string $data): array
    {
        return unserialize($data);
    }
}

Queue Connector: Create a Laravel queue connector for Enqueue:

namespace App\Providers;

use Illuminate\Queue\QueueManager;
use Enqueue\Client\ProducerInterface;

class QueueServiceProvider extends ServiceProvider
{
    public function register()
    {
        $this->app->singleton('beanstalkd', function ($app) {
            return new EnqueueProducer($app['enqueue.connection']);
        });
        $this->app->extend('queue', function ($queue, $app) {
            return new EnqueueQueue($queue, $app['beanstalkd']);
        });
    }
}

Middleware Chaining: Add custom middleware to Enqueue’s pipeline:

$middleware = new Middleware();
$middleware->add(new CustomMiddleware());
$producer->setMiddleware($middleware);

Config Quirks

Tube vs. Queue: Beanstalkd uses tubes (not "queues" like Laravel). Map Laravel queues to tubes in config:

'beanstalkd' => [
    'connection' => 'beanstalkd',
    'queue' => 'laravel-queue-name', // Maps to Beanstalkd tube
],

Visibility Timeout: Set visibility_timeout to prevent premature job release:
```
'options' => [
    'visibility_timeout' => 60, // 60 seconds
],
```
Memory Limits: Beanstalkd has a max-job-size (default: 64KB). Increase if needed:
```
beanstalkd -l 10485760 # 10MB max job size
```

Pheanstalk Laravel Package