PHP client

The Composer package is queen-mq/php-client, PSR-4 namespace Queen\. It requires PHP 8.3 or newer plus Guzzle 7 and ramsey/uuid. The client is synchronous: there is no promise or async variant. Laravel integration (service provider, facade, artisan command) ships in the same package and is optional. The source is prepared for the aligned release train, but Packagist has no tagged release yet; install it from the repository only if you intentionally accept that status.

use Queen\Queen;

$queen = new Queen('http://localhost:6632');

Constructor

new Queen(string|array $config = [])

A string is a single URL. An array with a numeric key 0 is a list of URLs. Anything else is a config array merged over Defaults::CLIENT_DEFAULTS; without url or urls it throws InvalidArgumentException('Must provide urls or url in configuration').

The load-balancing keys are inert with a single URL: the LoadBalancer is only constructed when urls holds more than one entry.

retry429

retry429 takes maxAttempts, baseMs and capMs, with the constants on Queen\Http\Retry429Policy (UNBOUNDED is 0), separate from retryAttempts; the defaults, the Retry-After contract and the jitter are in What the clients do with a 429. capMs has a hard 300,000ms ceiling so a single retry sleep remains operationally bounded.

Queen

ack

$message is a message array, a transaction-id string, or an array of messages. $status is true → completed, false → failed, or a status string passed through verbatim. $context accepts group and error.

partitionId is mandatory on every message array; without it the builder throws InvalidArgumentException. A leaseId is forwarded when present. Per-message statuses inside a batch work by tagging items with _status and _error.

One message posts to /api/v1/ack, more than one to /api/v1/ack/batch. Both respond with one result per ack in request order.

renew

Accepts a lease-id string, a message array, or an array of either. Posts to /api/v1/lease/{leaseId}/extend once per distinct lease id.

QueueBuilder

$queen->queue($name). Configuration methods return static; terminal methods are push(), pop(), consume(), getConsumer(), create(), delete(), dlq() and flushBuffer().

Addressing

Queue lifecycle

OperationBuilder exposes onSuccess(Closure), onError(Closure) and execute(): mixed.

Defaults::QUEUE_DEFAULTS carries nine keys: leaseTime, retryLimit, priority, delayedProcessing, windowBuffer, maxSize, retentionSeconds, completedRetentionSeconds and encryptionEnabled, with the values listed under Queue option defaults.

Extra keys you pass to config() are sent verbatim, so any option /configure accepts is reachable.

Since 1.6.0 /configure merges: an option the body does not carry keeps the value the queue already has, and only "mode": "replace" resets what the body omits. This client sends no mode, so create() always merges. Because config() merges over QUEUE_DEFAULTS, those nine keys are on the wire whether you named them or not and land on the client’s default rather than on the queue’s stored value; the twelve options outside that array, dedupWindowSeconds and retentionEnabled among them, are the ones a partial call now leaves alone.

Producing

Each item may carry data, payload, or be the payload itself. The client mints a UUIDv7 transactionId via Queen\Support\Uuid::v7() when the item has none.

PushBuilder exposes onSuccess(Closure), onError(Closure), onDuplicate(Closure) and execute(): mixed. execute() returns the broker’s per-item array for a direct push; a buffered push returns without sending once the buffer accepts the message. At maxSize waiting messages the add flushes inline and keeps retrying under a maxWaitMillis deadline; if the deadline expires it throws RuntimeException and the message was not accepted. PHP has no background flusher to wait on, which is why the bound is a deadline here rather than an open-ended park.

$queen->queue('orders')
    ->partition('customer-42')
    ->push([['data' => ['orderId' => 8891]]])
    ->execute();

Consuming

pop(): array

Returns a list of message arrays, [] when there is nothing to return. Route selection: queue plus non-Default partition uses /api/v1/pop/queue/:queue/partition/:partition; queue alone uses /api/v1/pop/queue/:queue; namespace or task alone uses /api/v1/pop.

popResult(): array

Returns ['messages' => array, 'autopilot' => array|null]. It is the same call as pop() and returns the messages plus the broker’s account of how it sized the claim: partitions, batch, and an optional waitMillis pacing hint the consume loop honours in place of its own delay between empty polls. autopilot is null when the pop did not engage autopilot, when the broker is older than 1.2, or when the answer was a bodiless 204, which has no body to carry an echo. See pop autopilot.

consume(Closure $handler): ConsumeBuilder

ConsumeBuilder exposes onSuccess(Closure), onError(Closure) and execute(): void.

getConsumer(): HighLevelConsumer

A pull-loop consumer modelled on php-rdkafka’s KafkaConsumer, for code that wants to own its own loop instead of handing over a closure.

consume() and consumeBatch() call pcntl_signal_dispatch() when the extension is available, so a SIGTERM handler you installed runs between polls. Long-poll timeouts and connection refusals are absorbed into null / []; every other exception propagates.

$message['trace']

Messages returned by HighLevelConsumer carry a trace closure:

$message['trace'](['traceName' => 'tenant-acme', 'eventType' => 'info', 'data' => ['step' => 1]]);

data is required; traceName accepts a string or an array of strings; eventType defaults to 'info'. It never throws: failures return ['success' => false, 'error' => ...].

Buffering

flushBuffer(): void flushes this builder’s queue/partition buffer; throws RuntimeException with no queue name. Buffers are keyed on "<queue>/<partition>", so builders addressing the same pair share one. A buffer flushes at messageCount messages or timeMillis after its first message.

The buffer is bounded and lossless under errors. A batch whose POST fails is restored to the front of the buffer, in order, and retried after retryDelayMillis; it is never dropped. At maxSize waiting messages an add flushes inline under the maxWaitMillis deadline and throws if it expires, so a broker outage surfaces as an exception with everything still queued, not as silent loss.

Dead-letter queue

dlq(?string $consumerGroup = null): DLQBuilder. Throws RuntimeException with no queue name.

Read-only. Replay lives on the admin façade: retryMessage(string $partitionId, string $transactionId).

Since broker 1.6.0 that route runs on a move: one transaction claims the newest dead-letter row at the address, pushes it back into the log and deletes the row, and the replayed message carries the deterministic transaction id dlq:<dead-letter row id>. A second call for the same address answers 404 rather than replaying a second copy, only the addressed consumer group’s record is removed, and a result: "duplicate" verdict means nothing was written and nothing was removed. See Messages and dead letters.

TransactionBuilder

$queen->transaction(). Pushes and acks in one PostgreSQL transaction, all-or-nothing.

$queen->transaction()
    ->ack($message)
    ->queue('orders.enriched')->push([['data' => ['id' => 1]]])
    ->commit();

A transaction is atomic, not exactly-once end to end; see the limit.

Admin

$queen->admin(). Every method returns the broker’s decoded body. Methods taking array $params turn it into a query string.

Resources

Depth is the lightweight scaling read: total pending, live-lease processing, claimable ready, their partition counts, and effectivePending / effectiveReady adjusted for conflation. Per-partition rows carry pending, processing and ready. It has no message timestamps or segment scan; older brokers may omit the lease-aware fields during a rolling upgrade.

Messages and traces

Status and analytics

Consumer groups

seekConsumerGroup posts $options verbatim: ['toEnd' => true] or ['timestamp' => '<RFC3339>'].

System

Errors

Non-2xx responses throw Queen\Exceptions\HttpException, with isClusterSuspended() and isRateLimited() helpers. The machine-readable codes are constants on Queen\Exceptions\ErrorCode, one per proxy code listed under Behind the proxy.

A 204 response yields null: a 204 carries no body at all.

Laravel integration

The package auto-registers Queen\Laravel\QueenServiceProvider and the Queen facade alias. Publish the config with the queen-config tag; it lands at config/queen.php. The provider binds Queen\Queen as a singleton and aliases it to queen.

Config keys and env vars

Facade

use Queen\Laravel\QueenFacade as Queen;

Queen::queue('orders')->push([['data' => ['id' => 1]]])->execute();

The facade proxies queue(), transaction(), admin(), ack(), renew(), flushAllBuffers(), getBufferStats() and close().

Laravel Queue driver

The provider also registers a queen Laravel queue connection. Existing jobs can use dispatch(), middleware, backoff and failed-job events unchanged:

QUEUE_CONNECTION=queen php artisan queue:work queen --queue=default --timeout=60 --tries=3

retry_after becomes the Queen lease duration and must exceed the worker/job timeout. block_for is the long-poll duration; leave it at 0 for a worker that scans a comma-separated priority queue list. Zero disables broker waiting but retains the normal 30-second request budget; positive values become the broker timeout and the HTTP client adds five seconds of transport slack.

The default prefetch=1 and ack_batch=1 keep the per-job synchronous ACK boundary. Short, idempotent workloads can opt into a larger prefetch; the connector then requires lease_renewal=true on every worker path. One pop feeds the standard sequential Laravel worker, while the helper keeps the active job, local tail and deferred acknowledgements leased. This remains at-least-once delivery and widens the crash duplicate window. An exact-PID SIGCHLD watchdog fences the worker if its helper disappears while a lease is active. The renewed profile requires Unix CLI PHP with PCNTL/POSIX support; application code must not replace Queen’s signal handler. Leave prefetch at 1 for unsupported platforms, strict per-job confirmation or comma-separated priority queues. A reentrant pop() before the active prefetched job is deleted or released fails explicitly.

Supervised workers validate timeout < retry_after; the driver also rejects an unsafe explicit per-job timeout when renewal is off. Laravel does not expose a direct queue:work --timeout value to the connection, so an external process manager must enforce that inequality itself.

Laravel Queue::bulk() is overridden with bounded multi-partition Queen push requests. bulk_batch limits each request; ordinary dispatch() remains a single-job operation.

Ordinary jobs are assigned deterministically to a bounded set of partition stripes. A job implementing Queen\Laravel\Contracts\QueenPartitionable::queenPartition() supplies its own ordering key instead. Delayed dispatch and positive backoff use Queen timers; an immediate release uses an atomic ack-and-push transaction. A positive backoff uses an atomic ack-and-timer transaction, and a final Laravel failure is acked to Queen’s DLQ. Laravel’s failed-job provider is decorated by default so retry, forget, flush and prune also remove the matching Queen snapshot. Failed payloads carry a stable retry transaction ID; queue:retry resets their attempt count and can safely bypass the original dispatch’s deduplication record. Use Laravel’s command for Laravel jobs, not generic Admin retryMessage(), because only Laravel owns the failed_jobs index.

Laravel Queue::size() obtains delayed work with the broker’s indexed count(queue, 'laravel:') timer operation, so it does not download keyset pages. The client falls back to legacy paging when the broker explicitly returns no_such_route/unsupported, or when the immediately preceding broker ignores mode=count and returns the exact, well-formed list-page contract. That page is reused as page one. Timeouts, 5xx responses, malformed pages, missing cursors and cyclic cursors remain visible errors instead of producing a plausible but partial size.

The driver can still run under any ordinary process manager. For Horizon-like local pools, the package also provides the PHP and Rust supervisors below; the Queen broker itself never spawns PHP workers.

The broker emits a group-scoped deliveryAttempt for every popped message. It increments after nack, worker crash or lease expiry; the driver combines it with explicit releases for Laravel attempts() and --tries. During a rolling upgrade an older broker’s missing field falls back to 1, so upgrade brokers before depending on crash-attempt enforcement.

Laravel monitoring reads the worker consumer group’s cheap depth endpoint. size() is total pending (including live leases) plus Laravel-owned timers, pendingSize() is claimable ready, and reservedSize() is live-lease processing. Missing lease-aware fields retain the previous counters during a rolling broker upgrade.

For oldest-job age, ready: 0 returns null without the segment-backed queue detail call. With ready work the depth response has no timestamps, so the driver filters queue detail to ready partitions and returns a conservative approximation. Queue detail uses the queue-wide worst cursor; its oldestMessage can therefore predate this group’s first unleased job. Older brokers use the same approximate fallback.

Worker supervisors

The guided configuration, platform matrix and production checks are in Worker supervisors. The PHP engine keeps one Laravel master resident:

php artisan queen:supervise

The separate Rust binary starts the same queue:work children after one temporary Artisan invocation resolves the versioned configuration. Install the package-pinned native asset explicitly, then use the Composer launcher:

php artisan queen:supervisor-install
vendor/bin/queen-supervisor --php php --artisan artisan
php artisan queen:supervisor-config --pretty

The online install succeeds only when a manifest and asset exist for the package-pinned supervisor/v* release. Preview packages do not guarantee published assets, so use the PHP engine or a verified local manifest/archive pair until the matching release is available. The immediate parent of supervisor_binary.install_path must be an existing real directory; the install leaf must be application-owned and must not be group- or world-writable. See Run the Rust engine for the secure path example and platform status.

The normal exporter redacts bearer tokens and header values. Pass --for-engine only when producing input for a supervisor engine; that form contains the credentials.

Each entry in supervisor.supervisors carries connection, consumer_group, an ordered queues list, Laravel worker options and its scaling policy.

Both engines use capped exponential restart backoff. Only the Rust engine opens a circuit after five consecutive crashes and permits one probe after the cooldown; the PHP engine has no open/probe phase and continues at restart_backoff_max.

The local control command is shared by both engines:

php artisan queen:supervisor status [--json]
php artisan queen:supervisor status --check # non-zero unless live
php artisan queen:supervisor pause
php artisan queen:supervisor continue
php artisan queen:supervisor terminate

Status, commands, the exclusive PID lock and duration telemetry live below state_directory. Pause/continue map to SIGUSR2/SIGCONT; termination sends SIGTERM and enforces shutdown_grace. This surface targets Unix and requires PHP pcntl.

QUEEN_URLS supplies failover broker endpoints for depth reads. Both v2 engines read the selected pool’s resolved Queen connections entry directly and build an isolated client from its endpoints, bearer token and validated headers; neither reuses a worker’s live Laravel client. QUEEN_SUPERVISOR_READ_BEARER_TOKEN may replace the worker token with a read-only one while retaining the other custom headers. Both engines poll in waves of at most 16 concurrent depth requests and fail over network/5xx errors. The exported JSON contains the read token and headers only with --for-engine: do not log that form, prefer piping it directly to the Rust process, and protect any credential-bearing --config file with mode 0600.

Supervisor dashboard

The package also provides a disabled-by-default local panel. It reads bounded state from the one local master and protects HTML, JSON and controls with the same viewQueenDashboard Gate. In production, enabling the route without defining an allowing Gate still returns 403.

The complete authorization example, route-cache procedure and local-versus-global scope are in Supervisor dashboard.

Artisan command

Registered only when running in console.

php artisan queen:consume orders "App\\Handlers\\OrderHandler"

The command errors out when the handler class does not exist.

Not in this client

There is no streaming SDK for PHP. The Stream builder, windows, gates and the /streams/v1/* runtime exist in the JavaScript, Python, Go and Rust clients.

Same surface, other languages

Parity here is a claim about the surface, not about shared code: each client is written natively in its own idiom. These sixteen rows are that surface, read out of clients/ on this tree. Six of them are full parity across all six clients; the other ten are where a client stops.

The ten divergent rows, with their conditions:

• Key/value. The seven operations are get, getMany, getPrefix, put, putIfAbsent, delete and incr. C++ wraps five of them: getMany and getPrefix have no method, and both remain reachable through POST /api/v1/kv on the shared HttpClient. getPrefix inside a transaction is refused by the broker in every client, which is its rule and not a client’s gap.
• Timers. C++ has schedule and cancel only; peek and list are reads and stay on GET /api/v1/timers/{queue}[/{timerKey}]. There is no reschedule operation anywhere, because schedule is the upsert and status reports which happened; Python, Go, Rust and PHP still spell a reschedule alias over it, JavaScript and C++ do not.
• once. JavaScript (kv.once, transaction().once) and Python (kv.once, transaction().once) fold putIfAbsent plus required into the question people actually ask, “did I win?”. The other four write the putIfAbsent themselves, which is the same wire and one line longer.
• kv on a streams operator context. No client has it, so it is not a row. Inside a stream the state primitive is state_ops, which commits with the sink and the ack in the cycle’s own transaction; a key/value write from an operator would not, and that atomicity is the thing the stream already gives you for free.
• Admin facade. C++ has no Admin class. Every management and observability route is still reachable, through the shared HttpClient returned by get_http_client().
• affinity. The C++ LoadBalancer implements round-robin and "session" only, and load_balancing_strategy = "affinity" falls through to round-robin silently. The strategy matters because it keeps one consumer’s pops on one backend, which is what keeps two clients from contending on the same partition claim.
• Streams. The Stream builder, the four window kinds, gates and the /streams/v1/* runtime are in the JavaScript, Python, Go and Rust clients. PHP and C++ have none of it.
• Lease renewal. In C++, renew_lease() sets a flag the consumer loop does not act on: the worker carries an unimplemented placeholder where the timer would go. Call client.renew(message) yourself before the lease expires.
• Per-message trace. Where it exists it is attached by the consume loop, so a message returned by a manual pop() never carries it. Rust records a trace through Admin::record_trace instead of hanging a method off the message. C++ cannot hang one off a JSON object at all, and its trace hook is an explicit no-op.
• Host override. JavaScript (hostHeader) and Rust (host_header) advertise a request authority, and a TLS SNI, independent of the address the socket dials. That is what addresses a named tenant cluster behind a shared proxy endpoint. The other four clients send the dialled address.
• pop failures. Go, Rust and PHP surface a 4xx, an exhausted 429 budget, a terminal 403 or a network fault to the caller, so an empty result means an empty queue. JavaScript, Python and C++ log the failure and return an empty result, which does not distinguish an empty queue from revoked credentials.

PHP is the one client with no suite in the test matrix: nothing in test/run.sh executes it. The rows above are read off clients/client-php/src, not off a run, and the package’s own tests/ directory is the only thing that exercises it.