Enqueue Rdkafka Serializer Bundle Laravel Package

Getting Started

• Prerequisites first. This bundle still sits on top of enqueue/enqueue-bundle and enqueue/rdkafka, so you need a working Enqueue setup (transports, clients, ext-rdkafka) before it does anything useful. Confirm that base wiring before adding serializer config.
• Install and register. composer require flaconi/enqueue-rdkafka-serializer-bundle, then add the bundle to config/bundles.php if it is not auto-registered in your Symfony version. Earlier 1.x/2.x releases predate modern Flex auto-registration, so verify registration manually.
• Version context matters. The current 2.4.0 line is not the 2019 snapshot: it adds Avro support. Still pin the version (^2.4) and check its Symfony/PHP constraints against your runtime, because the package has a small maintainer surface and sparse external usage.
• Look here first. Read src/DependencyInjection/Configuration.php and the extension class to see the config tree. For the new feature, inspect the Avro serializer wiring: selecting AvroSerializer now auto-configures AvroRecordSerializer. The README and tests/ remain the main documentation.
• First use case. Prove a round trip between producer and consumer. Start with JSON or PHP serialization on one transport, then move to Avro: configure a transport with the Avro serializer, produce a record, and consume it with matching Avro config to confirm the automatic AvroRecordSerializer setup behaves as expected.

Implementation Patterns

• Per-transport serializer selection. The core pattern is still declaring a serializer per transport/client rather than one global default. Set the transport's serializer to the service the bundle exposes, and keep producer and consumer config in the same file so drift is visible in review.
• Use Avro for schema-backed topics. With 2.4.0, selecting AvroSerializer automatically sets up AvroRecordSerializer. Use this for Avro topics where records need schema-aware encoding/decoding, and keep the schema registry/client configuration explicit in your transport config.
• Keep DTOs serializer-friendly. With JsonSerializer, message objects need to be cleanly JSON-encodable and reconstructible on the consumer. For Avro, model messages against the Avro record schema rather than passing loose arrays; validate records before publishing.
• Multi-transport topology. When one app produces to several topics with different formats (legacy PHP-serialized topic vs. JSON vs. Avro), define distinct transports/clients and attach the appropriate serializer to each. This remains the bundle's reason to exist.
• Symfony wiring tips. Override or decorate the serializer service in services.yaml for custom normalization (dates, enums, money objects). Register a custom serializer as a service and reference it from transport config. For Avro, prefer the bundle's automatic AvroRecordSerializer setup unless you need a custom record serializer.
• Consumer daemon setup. Run consumers via the Enqueue consume command with the transport name. Ensure the same serializer is configured on the consuming transport, especially for Avro, or you will get decode failures that look like broker problems.
• Testing pattern. Integration-test the round trip: publish with the configured producer, consume with the configured consumer, assert the DTO or Avro record hydrates. Add one Avro round-trip test if you adopt the new serializer, plus unit tests for any custom serializer.

Gotchas and Tips

• Avro auto-wiring is convenient but implicit. 2.4.0 sets up AvroRecordSerializer automatically when you select AvroSerializer. If your app already defines a custom AvroRecordSerializer service, check service precedence and decoration order; otherwise your custom serializer may be replaced or duplicated. Use bin/console debug:container to confirm which service is active.
• Avro adds schema-registry concerns. The automatic record serializer does not remove the need to configure a schema registry or schema resolution strategy. Missing or misconfigured registry settings produce failures at produce/consume time, not necessarily at container compile time.
• Producer/consumer serializer mismatch is the classic failure. Symptoms are opaque decode errors or empty message bodies. Always confirm both sides point at the same serializer; add smoke tests that publish and consume in CI, covering Avro if used.
• Container compilation failures. If the bundle's extension references services or config keys that changed in your Enqueue/Symfony version, you'll get compile-time errors. Debug with bin/console debug:container and bin/console debug:config (or config:dump-reference) to see what registered.
• Small adoption surface. The package has limited community coverage, so source and tests remain ground truth. The 2.4.0 Avro auto-setup is useful but new; verify it against your Symfony and enqueue/rdkafka versions and write your own integration tests.
• Serialization is not schema management. Neither this bundle nor Enqueue enforces message versioning. For Avro, rely on schema evolution rules; for JSON/PHP payloads, add an explicit version field or use tolerant readers so format changes don't break in-flight consumers.
• Extension points. The main seams are the serializer service (swap/decorate it) and transport configuration (override per environment). For Avro, you can also replace or decorate the auto-configured AvroRecordSerializer if schema handling needs customization. Prefer decorating Enqueue/bundle services over patching the bundle so changes survive composer update.
• Migration advice. If you only need one format, native enqueue/rdkafka transport config (setting serializer per transport) may still cover your need without this bundle. The bundle is most useful when you need per-transport serializers or want the 2.4.0 Avro auto-setup without hand-wiring the record serializer.