Download the PHP package babelqueue/symfony without Composer

BabelQueue for Symfony

Polyglot Queues, Simplified. A Symfony Messenger serializer that speaks the canonical BabelQueue envelope — so your Symfony services exchange messages with Laravel, Go, Python, .NET and Node over one strict JSON format, on the broker you already run.

This is the Symfony adapter. It plugs into Symfony Messenger: you keep Messenger's transports, handlers, worker and retry — BabelQueue only changes the wire format to the language-agnostic envelope (built by the shared core, babelqueue/php-sdk). The full standard is documented at babelqueue.com.

Requirements

• PHP ^8.2
• Symfony ^6.4 | ^7.0 (Messenger)
• A broker Messenger supports (AMQP/RabbitMQ, Redis, …)

Installation

Enable the bundle (if you don't use Symfony Flex) in config/bundles.php:

Configuration

Point a Messenger transport at the BabelQueue serializer, and map inbound URNs to message classes:

Idempotency (deduplicate redeliveries)

Brokers deliver at least once, so a worker can see the same logical message twice (a redelivery after a crash, a visibility-timeout expiry, a fan-out). Enable the idempotency middleware to deduplicate on the envelope's canonical meta.id, so a handler runs once per message. It's opt-in and off by default — leaving it disabled changes nothing.

How it behaves, per inbound delivery (keyed on meta.id):

• first delivery → the handler runs once; on a clean return the id is recorded.
• a duplicate (same meta.id already recorded) → the handler is skipped and the message is acked, so the broker stops redelivering.
• the handler throws → the id is not recorded and the error propagates, so Messenger's retry / failure transport still apply and a later delivery runs again.
• a message with no usable id → handled unchanged (fail-open).

The default in-memory store is process-local — fine for a single worker or tests, but a fleet of workers must share one store. Point store at a service implementing BabelQueue\Idempotency\IdempotencyStore (from babelqueue/php-sdk), such as the persistent PdoStore (Postgres / MySQL / SQLite) or RedisStore:

If the configured store implements BabelQueue\Idempotency\ClaimingStore (the persistent PdoStore / RedisStore do), the middleware uses an atomic claim: of N concurrent deliveries of the same id, exactly one runs the handler; the rest are parked (redelivered later, not acked) until the winner commits. ttl bounds a crash between claim and commit. This is still at-least-once, never exactly-once — keep handlers idempotent.

A message

Implement BabelQueue\Symfony\Contracts\PolyglotMessage:

Produce & consume

On the wire it becomes the canonical envelope, readable by every BabelQueue SDK:

Run the worker as usual: php bin/console messenger:consume babel.

How it maps to Messenger

• Routing is Messenger's job: it routes the decoded message class to a handler.
• Retry bridges both ways — Messenger's RedeliveryStamp ⇄ the envelope's top-level attempts.
• Tracing — the inbound trace_id is attached as a BabelTraceStamp. With babelqueue.messenger.trace_middleware on the bus (see config above), any message a handler dispatches automatically inherits that trace_id, so a whole chain stays in one trace. A message that pins its own BabelTraceStamp or implements HasTraceId keeps its explicit id.
• Unknown URN — a message whose URN isn't mapped throws MessageDecodingFailedException, so Messenger routes it to your failure transport (the idiomatic Symfony behavior).
• Idempotency — with babelqueue.messenger.idempotency_middleware on the bus (opt-in, see above), a redelivery of the same meta.id is acked without re-running the handler. The id is surfaced on decode as a BabelMessageIdStamp.

Testing

License

MIT © Muhammet Şafak. See LICENSE.