Symfony Laravel Package

Getting Started

1. composer require babelqueue/symfony
2. Register the bundle — Symfony Flex may not have a recipe given the package's age, so expect to add it by hand:

   // config/bundles.php
   BabelQueue\Symfony\BabelQueueBundle::class => ['all' => true],
   

3. Point one Messenger transport at the BabelQueue serializer instead of the default messenger.transport.native_php_serializer. Keep your Symfony-to-Symfony transports on the native serializer — you only want the canonical envelope on polyglot boundaries.
4. Configure the inbound URN → message-class map described in the README. This is what turns an envelope produced by a Go/Python/Node service into a class your #[AsMessageHandler] can receive.
5. First use case: publish a single, low-risk event from Symfony that a non-PHP consumer already reads (or consume one they already publish), and confirm the JSON on the wire matches the spec at babelqueue.com before touching anything critical.

Where to look first: config/packages/messenger.yaml (serializer wiring), the bundle's URN-map config block, and the babelqueue/php-sdk envelope class — that's where the actual JSON shape lives. The Symfony adapter is thin; almost all behavior is in the SDK.

Implementation Patterns

Serializer at the transport level, not globally. Set the BabelQueue serializer on the specific transport(s) that cross language lines. This keeps internal Symfony messages using PHP-native serialization (faster, handles more types) while only paying the JSON/envelope tax at the boundary.

Outbound: plain Messenger messages. Define small DTOs, dispatch through the normal MessageBusInterface, and let the serializer build the envelope. Keep message classes dumb — scalars, arrays, and nested DTOs that map cleanly to JSON. Anything that doesn't survive json_encode/json_decode will bite you.

Inbound: URN map is your routing table. Add one entry per external message type. Handlers stay idiomatic Symfony:

#[AsMessageHandler]
final class HandleOrderShipped { public function __invoke(OrderShipped $m): void { /* ... */ } }

No special base class, no adapter in the handler — that's the main ergonomic win.

Contract-first testing. Since the wire format is the product, unit-test the serializer round-trip without a broker: serialize a message, assert the JSON against a golden fixture, deserialize it back. Commit those fixtures to a shared repo/package so the Go, Python, and Node teams assert against the same bytes. This is the single highest-value habit with a polyglot envelope.

Failure transport parity. If you use failure_transport, configure it with the same BabelQueue serializer, otherwise failed envelopes become unreadable by messenger:failed:show and messenger:failed:retry.

Versioned payloads. Treat the envelope version field as an API contract. Add fields additively, never rename/remove without a coordinated rollout — you cannot atomically redeploy five languages.

Gotchas and Tips

• Maturity risk. One star, zero dependents, first release in late 2026. Pin an exact version, read the CHANGELOG and releases before every bump, and be prepared to fork. The saving grace is that the adapter is small and the real surface is babelqueue/php-sdk.
• Don't mix serializers on one queue. Messages already in the queue in Symfony's native format will fail to decode after the switch. Drain the queue or use a new queue name during migration.
• JSON type loss. DateTime becomes a string, integers beyond 2^53 lose precision in JS consumers, null vs. absent keys are not the same thing, and PHP associative arrays vs. lists can serialize unexpectedly. Normalize on the producer side rather than patching consumers.
• Debugging. messenger:consume -vv surfaces decode errors, but the fastest path is inspecting the raw payload with rabbitmqadmin/redis-cli — it's human-readable JSON, so you can see exactly what the producer sent versus what your URN map expects.
• Fail fast on unknown URNs. An unmapped inbound URN should blow up loudly at worker start or first consume, not silently retry forever into your failure transport. Test this explicitly.
• Config quirks. Without a Flex recipe you're hand-editing config/packages/messenger.yaml; get the serializer service id right and confirm with bin/console debug:container | grep -i babel.
• Version constraints. PHP ^8.2, Symfony ^6.4 | ^7.0. Check compatibility before a Symfony major upgrade — a thin adapter can still hard-block your framework upgrade.
• Extension points. Wrap the serializer in a decorator if you need tracing headers, envelope logging, or metrics — cleaner than modifying package internals. If the bundle exposes a custom URN resolver, use it rather than string-concatenating URNs in message classes.
• Performance. JSON encoding is negligible; broker message-size limits and large nested payloads are the real ceiling. Keep envelopes lean — send IDs and fetch details on the consuming side where possible.