Pheanstalk Laravel Package

Getting Started

Start by installing pda/pheanstalk via Composer (composer require pda/pheanstalk). Ensure your environment runs PHP 8.1+ and has beanstalkd running (e.g., beanstalkd -l 127.0.0.1 -p 11300). First use cases are straightforward:

• Producer: Use Pheanstalk::create() to instantiate the client, then useTube(new TubeName('...')) followed by put(...) to enqueue jobs.
• Consumer: watch() a tube, then reserve() or reserveWithTimeout($seconds) to fetch jobs, process them, and delete() or release() accordingly.
  For workers, wrap your job loop in a long-running process (e.g., systemd service) and ensure reserveWithTimeout() is used to avoid hanging indefinitely.

Implementation Patterns

Leverage the role-based interfaces (PheanstalkPublisherInterface, PheanstalkSubscriberInterface, PheanstalkManagerInterface) for precise dependency injection. For example, inject PheanstalkPublisherInterface in your job-queuing service to make the producer logic testable and decoupled. Use TubeName objects instead of strings everywhere — it enforces validation and prevents tube name typos at runtime.

Implement workers with explicit error handling: delete() on success, bury() on unrecoverable errors, and release() for retryable failures. Always call touch($job) for long-running tasks to prevent timeout-based rescheduling. Where reliability matters (e.g., payment processing), wrap reserveWithTimeout() in a while(true) loop with logging and exception handling that causes process exit (e.g., for supervisor/systemd restart).

Store job payloads as JSON (with JSON_THROW_ON_ERROR) and deserialize in the worker. Inject factories (e.g., TaskFactory) to convert raw payloads into typed domain tasks, avoiding fragile unserialize() usage.

Gotchas and Tips

• No method chaining: v5+ does not support chaining like ->watch()->reserve() — call methods sequentially to avoid protocol state confusion.
• Timeout consistency: Ensure Connection::setReadTimeout() and Connection::setWriteTimeout() are ≥ reserveWithTimeout(); otherwise, v8+ throws ConnectionException when no jobs arrive (a breaking change for v8).
• Reconnection pitfalls: Automatic reconnection was added in v5.11+, but avoid shared connections across threads or forks. Prefer short-lived processes (supervised) over persistent SAPIs (e.g., FPM).
• Resource cleanup: Use disconnect() (v7+) or close() (v5.1+) to release sockets deterministically — especially important in CLI workers or before pcntl_signal handlers.
• Error handling: Beanstalkd protocol exceptions (e.g., TubeNotFoundException) now include tube names in v7.0.1+, but always catch \Pheanstalk\Exception\ServerException and its subclasses for robust workers.
• Testing: Mock PheanstalkSubscriberInterface for unit tests. For integration, run beanstalkd in a Docker Compose service (as suggested by composer test docs).