Queue Laravel Package

Getting Started

This package is not intended for direct use in Laravel projects. It’s a read-only mirror of queue functionality tightly coupled to the Spiral framework and RoadRunner server. If you're using Laravel, do not install spiral/queue—it is incompatible with Laravel’s Illuminate\Contracts\Queue contract, job serialization, and queue driver ecosystem. For background jobs in Laravel, use the built-in queue system (with Redis, database, or SQS) and optionally integrate with RoadRunner only at the server level via the official laravel/roadrunner package (which handles HTTP server configuration, not queue logic).

If you are using Spiral (e.g., via spiral/roadrunner), begin by:

1. Installing the RoadRunner binary (rr) and enabling the PHP worker extension.
2. Installing spiral/roadrunner (which transitively includes queue capabilities).
3. Configuring queues in .rr.yaml, defining brokers (e.g., redis, amqp) and job handlers.
4. Implementing jobs as classes implementing Spiral\Queue\JobInterface or using provided traits.

Implementation Patterns

• Job Dispatching: Inject Spiral\Queue\QueueInterface and call $queue->push($job) or $queue->delay($seconds, $job). Avoid blocking calls in HTTP requests—enqueue for async processing.
• Job Handlers: Register handlers in .rr.yaml under queues.handlers, mapping job classes to handler classes implementing Spiral\Queue\HandlerInterface. Use dependency injection in handlers via Spiral’s container.
• Broker Scaling: Configure concurrent workers per broker (e.g., amqp: {numWorkers: 8}) to match throughput needs. Prefer Redis or RabbitMQ for reliability.
• Job Graphs: For complex workflows, use Spiral\Queue\JobGraph (advanced) to chain dependent jobs—only if idempotency and failure recovery are well-architected.
• Testing: Unit-test handlers in isolation. For integration, use Spiral\Queue\Testing\QueueSpy to assert dispatched jobs without sending to actual brokers.

Gotchas and Tips

• Framework Mismatch: Laravel developers often mistakenly assume this integrates with Laravel’s queue system. It does not. spiral/queue ≠ laravel/queue. Mixing them requires rewriting all queue logic—avoid entirely unless migrating to Spiral.
• State Leaks: RoadRunner uses long-lived PHP workers. Jobs sharing state (e.g., cached clients, closures over mutable variables) will cause bugs. Always reset dependencies per-job (use constructor injection, not properties that mutate).
• No Built-in Retries: Unlike Horizon, retry logic must be implemented manually or via config (e.g., retries: 3 per broker). Ensure jobs implement Spiral\Queue\RetryableJobInterface and handle Spiral\Queue\RetryException.
• Silent Failures: Uncaught exceptions may terminate workers without logs unless you enable RoadRunner’s logging and metrics. Configure log: {level: debug} and /metrics endpoint.
• Config Location: RoadRunner defaults to .rr.yaml in the current directory. Always specify -c path/to/.rr.yaml in scripts to avoid environment mismatches.
• Dependencies: This package is auto-generated from spiral/roadrunner. Always check RoadRunner’s Changelog for breaking changes—even patch updates may alter queue behavior.