Download the PHP package babelqueue/laravel without Composer

BabelQueue for Laravel

Polyglot Queues, Simplified. A drop-in Laravel queue driver that produces a strict, language-agnostic JSON envelope — so Go, Python, Java, .NET and Node.js services can consume your jobs without PHP's serialize().

Laravel's native queue serialises jobs with PHP serialize(), producing an object graph only PHP can read. BabelQueue replaces just the serialization layer with a frozen JSON envelope and URN-based routing, over the broker you already run (Redis or RabbitMQ). No sidecar, no proxy, no broker plugin.

This is the PHP/Laravel SDK. The full cross-language standard and the canonical wire contract are documented at babelqueue.com.

Requirements

• PHP ^8.2
• Laravel ^11.0 | ^12.0
• Redis or RabbitMQ

Installation

Add a polyglot connection to config/queue.php:

The wire envelope

Every message is encoded as this frozen, schema_version: 1 envelope (full spec at babelqueue.com):

• job — the message URN, never a class name. Convention: urn:babel:<context>:<event>.
• trace_id — cross-service correlation id, preserved across every hop.
• data — your pure-JSON payload.

Producing messages

Typed job (primary):

Facade (sugar):

Continuing a trace from a handler? Implement BabelQueue\Contracts\HasTraceId on the downstream job (or pass the traceId argument) and the inbound trace_id is forwarded instead of a new one being minted.

Consuming messages

Map URNs to handlers in config/babelqueue.php:

Run a worker against the polyglot connection like any other:

Unknown URNs

config/babelqueue.php → on_unknown_urn: fail (default) · delete · release · dead_letter.

Dead-letter queue (cross-language)

Enable in config/babelqueue.php:

Permanently-failed (and, with on_unknown_urn => 'dead_letter', unroutable) messages are republished to the DLQ as the same envelope plus an additive dead_letter block (reason, error, failed_at, original_queue, attempts, lang). Because the DLQ is an ordinary queue, any SDK can triage it.

Idempotent consumption (opt-in)

Brokers deliver at least once: a redelivery after a missed ack — or a fan-out — can hand a consumer the same message twice. Enable idempotency to dedupe deliveries on the envelope's canonical per-message identity, meta.id, so a duplicate delivery is a no-op and the first delivery runs the handler exactly once. It is off by default and never changes the wire envelope.

Enable in config/babelqueue.php:

The default backends are Laravel-native and reuse infrastructure you already run:

• redis — over a Laravel Redis (predis) connection.

• database — over a Laravel DB connection (PostgreSQL / MySQL / SQLite). Create the table once at deploy time:

• memory — single-process only (tests / a lone worker); not shared, not persistent.

redis and database are claiming stores: when two workers receive the same meta.id concurrently, exactly one runs the handler and the other parks for redelivery — closing the in-flight window, not just deduping after success.

It binds the php-sdk IdempotencyStore in the container, so you can rebind it to a custom store:

A thrown handler leaves the id unmarked, so retry / DLQ still apply and a later delivery re-runs it. A message with no usable meta.id always runs (fail-open).

Testing

Links

• Website & docs (incl. the canonical wire contract): https://babelqueue.com
• Changelog: CHANGELOG.md

License

MIT © Muhammet Şafak. See LICENSE.