Laravel queue driver: install and run your jobs

QueenMQ can take over two jobs in a Horizon setup: holding the jobs, which Redis does today, and running the workers, which Horizon’s master does. Your job classes stay ordinary Laravel jobs, and queue:work stays the worker.

If you run Horizon today, Queen or Horizon compares the two, and migrate from Horizon moves a running application step by step.

Install

That is a working integration, with no supervisor. Keep your current systemd, Kubernetes or Supervisor definition if a fixed number of workers is all you need, and stop a worker with the signal you already use.

retry_after in config/queen.php, 90 seconds by default, is the Queen lease: how long a worker holds a job before the broker gives it to someone else. It must be longer than the worker’s --timeout and than the slowest job, unless you turn on lease renewal. Laravel does not pass queue:work --timeout to the connection, so without lease renewal the driver checks only a job’s own $timeout against the lease. A Queen supervisor refuses a pool whose timeout is not shorter than retry_after; under any other process manager, keep --timeout below retry_after yourself.

The consumer group is the name under which your workers share the work: two applications in one group split the jobs between them, and two groups on one queue each get every job, because the driver subscribes each new group to everything the queue holds. Give each application and environment its own queue names (or its own broker) and its own group.

When the broker requires a credential, set QUEEN_BEARER_TOKEN: a broker JWT with the read-write role, or, through the broker’s embedded proxy, an API key with the produce, consume and read scopes. The proxy classifies the deletion of a dead-letter entry as queue administration, so with failed-job sync on (the default) that key needs the admin scope too, or queue:retry and queue:forget fail before they touch Laravel’s row. Behind the proxy the cluster’s plan also caps the partitions per queue (8 on free, 64 on dedicated-s, see tenants), so keep QUEEN_PARTITIONS within it, and remember that every entity a QueenPartitionable job names is a partition too.

You need PHP 8.3 or later. The queue connection needs no extension unless you turn on push_compression or framed_pop, which need zstd; the supervisors need pcntl and posix on Unix. Every key of config/queen.php, its default and the 20 environment variables the file reads are in the configuration reference.

That is a working integration, with no supervisor: keep your systemd, Kubernetes or Supervisor definition if a fixed number of workers is all you need.

Three settings to know from the first day:

• retry_after (90 seconds) is the lease: how long a worker holds a job before the broker gives it to someone else. Keep it longer than the worker’s --timeout and the slowest job, or turn on lease renewal. Laravel does not pass --timeout to the connection, so keep the two in step yourself; a Queen supervisor refuses a pool whose timeout is not shorter than retry_after.
• The consumer group is the name under which your workers share the work. Two applications in one group split the jobs; two groups on one queue each get every job. Give each application and environment its own queues and its own group.
• QUEEN_BEARER_TOKEN, when the broker asks for a credential: a JWT with the read-write role, or a proxy API key with produce, consume, read, and admin for queue:retry and queue:forget.

You need PHP 8.3 or later; the supervisors need pcntl and posix, and the binary forms need zstd. Every setting is in the configuration reference.

Order jobs per entity

By default the driver spreads jobs over 64 partitions of the queue (laravel-0000 to laravel-0063), by a hash of each job’s id. A job that implements QueenPartitionable names its own partition:

use Illuminate\Contracts\Queue\ShouldQueue;
use Queen\Laravel\Contracts\QueenPartitionable;

final class RebuildCustomer implements ShouldQueue, QueenPartitionable
{
    public function __construct(public string $customerId) {}

    public function queenPartition(): string
    {
        return 'customer:'.$this->customerId;
    }
}

Every RebuildCustomer of one customer now runs in dispatch order, one at a time, and customers never wait for each other. The ordering example runs it on four workers and checks the order.

Choose a delivery profile

Three profiles cover most applications. They differ in how many round trips to the broker a worker waits for: every write a worker waits for is an fsync on the broker.

Medians of three runs on the Linux server, with the Rust supervisor and prefork (benchmark).

Safe

One acknowledgement per job: the worker asks for a job, runs it, and waits until the broker stored its ack. Start here while you validate a migration.

// config/queen.php
'prefetch' => 1,
'ack_batch' => 1,

Balanced

prefetch 'auto' sizes each pop from how long the jobs take: about 250 ms of work per batch, up to 16 short jobs, one long job. With short jobs a worker pops about once every 15 jobs; with jobs of 200 ms or more it keeps one per pop, so it never holds work another worker could run.

// config/queen.php
'block_for' => 1,
'prefetch' => 'auto',
'lease_renewal' => true,
// in each pool under supervisor.supervisors
'sleep' => 0,

With sleep 0 an idle worker waits on the broker (block_for) instead of sleeping, so it takes a job the moment one arrives: Laravel’s sleep 1 left a burst to the few awake workers, at a p99 of 338 ms in one run. A crash the lease renewer cannot hand back delivers the rest of the batch again, so keep tries at 2 or more.

Fast

Balanced, plus the two settings that take the last round trips off the worker’s path: ack_async sends the ack and starts the next job without waiting for the answer, and pop_ahead sends the next pop while the last job of a full batch runs.

// config/queen.php
'block_for' => 1,
'prefetch' => 'auto',
'lease_renewal' => true,
'ack_async' => true,
'pop_ahead' => true,
// in each pool under supervisor.supervisors
'sleep' => 0,

The price is a wider at-least-once window. The connector refuses prefetch above 1 and pop_ahead without lease_renewal, and ack_async needs ack_batch 1. A refused asynchronous ack is learned one job later, reported through Laravel’s exception handler, and that job runs again after its lease. Details are in prefetch, ack_async and pop_ahead.

What Laravel keeps

All 32 Laravel queue features we checked (chains, batches, unique jobs, rate limits, middleware, encrypted jobs, queued listeners and notifications, the failed-job commands) behave as the Laravel documentation says (the list).

Who runs the workers

Both supervisors read the same supervisor section of config/queen.php, publish the same status and obey the same commands, and both offer, beyond Horizon’s pools, coordinated replicas, prefork workers and event-driven scaling. Start with worker supervisors, then the dashboard, Kubernetes and monitoring. Read the production checks before you replace Horizon.

Versions

The PHP client is queen-mq/php-client on Packagist; the Rust supervisor is a separate binary whose version each client release pins. These pages describe PHP client 2.5.0, which pins supervisor 0.8.1, published for Linux (amd64, arm64) and macOS with a signed manifest. Everything not listed works from 1.6.0.

Limits

• Delivery is at least once, as on Redis: a lease expiry or a crash can run a job twice, so a job with an external effect needs an idempotency key.
• A job waits for the job ahead of it in its partition. A long job delays the short jobs that hashed to its partition, even while other workers are idle: give long jobs a queue of their own. A released job goes to the back of its partition.
• One supervisor master per application and consumer group, unless every replica runs with coordination.
• The supervisors and the dashboard are previews, on Unix only.
• Horizon still does things QueenMQ does not: silenced jobs, job lists, batches in its dashboard, Slack and SMS alerts, per-supervisor controls, clearing a queue (queue:clear fails and the jobs stay).

Messages other services push to QueenMQ, which are not Laravel jobs, go to a class of yours with php artisan queen:consume.