Avro Regy Laravel Package

Getting Started

Start by confirming the Symfony/Laravel gap. koco/avro-regy is a Symfony Messenger bundle, so Laravel package auto-discovery won't find it and there's no service provider or facade. v1.2.0 doesn't change that — it's a feature bump, not a Laravel bridge. You still have three realistic options: run it inside a sidecar Symfony Messenger worker alongside your Laravel app, treat it as a reference implementation and port the serialization logic into a custom Laravel queue serializer, or import the relevant classes directly and wire them yourself. Decide which before writing any code — this is the single biggest fork in the road.

Minimal install path:

• composer require koco/avro-regy:^1.2 and then read the resulting vendor/koco/avro-regy/composer.json to see exactly which Symfony and Avro PHP constraints were resolved. The base release is still an October 2022-era codebase, so expect Symfony 5.4/6.x era dependencies even on the newer tag.
• You'll need a Confluent-compatible Schema Registry running somewhere (Docker Compose is fine) and an Avro PHP implementation. The bundle assumes both are present.
• If your registry sits behind basic auth, an API key (Confluent Cloud), mTLS, or a proxy, you now get first-class support for that via the new requestOptions config — no forked client needed. Confirm the option shape in DependencyInjection/ rather than guessing at the README.
• In Symfony, register the bundle manually in config/bundles.php. In Laravel, skip the bundle registration and instantiate the underlying classes from a custom service provider or a queue serializer.

Read, in this order:

1. README.md — the config tree (registry URL, subject naming strategy, serializer registration, and now requestOptions).
2. DependencyInjection/ — the extension class enumerates every config key and its default. In a small bundle this is the documentation; the README will be thinner than you expect. This is where you confirm exactly how requestOptions is forwarded.
3. The class implementing Symfony's Messenger SerializerInterface — this is the code you'll actually reuse, subclass, or copy.
4. composer.json — tells you which Avro library and Symfony minor you're pinned to.

First use case: register one flat scalar record schema (e.g. OrderPlaced) under orders-value, publish one message through the serializer, then consume it and confirm the decoded array round-trips. Don't start with nested records, unions, or logical types — start with something flat so you can hexdump the wire bytes and verify the magic byte + schema ID prefix. Once that round-trips against a plain local registry, re-run it against an authenticated registry with requestOptions set, so you validate the new feature before it's a blocker in staging.

Implementation Patterns

Laravel-side integration. The most practical adoption is a custom queue serializer or a queue middleware that transforms specific jobs. Two patterns work well:

• Envelope wrapper: take Laravel's serialized job array, convert it into an Avro record matching a registered schema, and store schema_id plus the binary payload in the queue row's data column. Decode on the worker before dispatch().
• Marker interface middleware: only jobs implementing AvroEncoded get Avro treatment; everything else passes through as normal JSON. This lets you adopt Avro incrementally instead of forcing the whole application onto it.

Registry client configuration (requestOptions). This is the headline of v1.2.0 and it's the one piece of the bundle you'll likely touch in the Laravel path even if you don't use the bundle itself. Use it to:

• Authenticate — set the Authorization/API-key headers in one place rather than hand-rolling a Guzzle client. This removes the previous "fork the client to add credentials" step for Confluent Cloud and locked-down on-prem registries.
• Set timeouts — a short connect timeout plus a modest read timeout. Default HTTP client timeouts are often the reason a registry hiccup turns into a stalled worker.
• Enable TLS — CA bundle paths, client certificates, or disabling verification only in local Docker environments.
• Proxy and retries — route through an egress proxy, or configure retry/backoff at the HTTP-client layer instead of wrapping every registry call in your own retry loop.

Because it's a passthrough to the underlying HTTP client, treat it as config you must test, not config you can reason about: a wrong option key is often silently ignored rather than rejected. Write one test that hits an authenticated registry and asserts a 401 becomes a clear exception.

Schema management.

• Keep .avsc files under resources/avro/ or a dedicated schemas/ directory, and publish them to the registry during deploy via a small artisan command (walk the directory, POST each file to /subjects/{subject}/versions).
• Adopt a deterministic naming convention mapping class → subject, e.g. App\Events\OrderPlaced → orders-value. Inconsistency here is the root cause of most "it worked in staging" incidents.
• Keep schemas in version control and tag registry versions with your git SHA so you can correlate a bad message to a schema revision.

Consumer-side.

• Cache schema_id → schema locally (file cache or Redis). The bundle is thin; caching is your responsibility. Hitting the registry on every message is a latency and availability problem — and now that you can tune timeouts, the natural next step is to avoid the call entirely on the hot path.
• Decode at the edge of the system, then dispatch a normal Laravel job. The rest of the application should never see binary payloads.

Symfony transport scoping. If you do end up inside Symfony Messenger, register the bundle's serializer per transport rather than as the default. Setting it globally will attempt to Avro-encode every message, including ones your other services expect as JSON.

Testing.

• Run a throwaway Schema Registry in Docker Compose, point the config at it, and do a full publish/consume round-trip in a feature test.
• Add a second fixture test against an authenticated registry using requestOptions, so credential and header regressions surface in CI, not during a deploy.
• Add a contract test that decodes a captured fixture payload against the current schema, so any schema edit fails fast in CI rather than in production.

CI/CD.

• Gate deploys on the registry's compatibility check (usually BACKWARD). Call the compatibility endpoint or use a schema CLI before deploying.
• Pin both the Avro library version and the registry compatibility mode in documentation — the pairing is what determines whether a deploy is safe.

Gotchas and Tips

• Not a Laravel package. No service provider, no facade, no auto-discovery, no config/avro-regy.php published for you. Budget real time for the glue layer. v1.2.0 is additive and does nothing to close this gap.
• Upgrade to v1.2.0 is low-risk but not zero-risk. The changelog shows a single feature commit (requestOptions for the schema-registry client) with no stated breaking changes, but you're jumping 1.0.1 → 1.2.0 with no published notes for 1.1.0. Diff DependencyInjection/ and the client construction between tags before assuming a drop-in upgrade — the config tree is the thing that shifts in small bundles.
• requestOptions is opaque passthrough. Unknown keys may be ignored rather than rejected, so a typo looks like "auth works everywhere except production." Assert on real registry responses in tests, and log the effective config (with secrets redacted) at boot.
• Maintenance risk remains high, but it's not abandoned. Three stars, zero dependents, and a long dormancy between the 2022 base release and this one. A merged feature PR is a positive signal, not a guarantee — still treat it as vendored code: pin a commit, be prepared to fork for PHP 8.2/8.3 compatibility fixes, and run composer audit over the transitive Avro and Symfony dependencies.
• Version skew is the top failure mode. The Avro PHP library the bundle pins and the one you want may not be compatible. Check composer.json before assuming a modern flix-tech/avro-php will drop in.
• The registry is a runtime dependency. If serialization happens during a web request, a registry outage takes down your app. The new requestOptions lets you set sane timeouts and retries, which is mitigation, not a fix: serialize lazily in the worker, or cache aggressively, and have a documented fallback path.
• Subject naming is the #1 silent bug. Producer registers orders-value, consumer reads order-events-value, and everything "works" until it quietly doesn't. Log both the subject and the schema_id on producer and consumer side.
• Compatibility surprises. Changing a field's default, reordering enum symbols, or narrowing a type will fail registration under BACKWARD. Test registration in CI, not in production.
• Unions and null are where Avro PHP libraries diverge. Write an explicit test for every optional field; behavior differences here are subtle.
• Debugging binary payloads. The Confluent wire format is a magic byte plus a 4-byte schema ID, then the body. Log the schema ID and the decoded array before dispatch. Keep a toggleable "raw payload" log channel that's off in production but easy to flip on during an incident.
• Extension points are limited. The bundle is small enough that subclassing the serializer, decorating it in the container, or just reimplementing SerializerInterface yourself is usually faster than fighting the bundle's opinions. For per-topic behavior you'll almost certainly need your own wrapper.
• Weigh build vs. adopt for Laravel-only teams. A custom serializer is often ~200 lines, fully typed, and free of Symfony baggage — and with requestOptions now available as a reference, wiring an authenticated registry client yourself is a shorter task than it was a release ago. For most Laravel shops that still beats maintaining a bridge to a low-adoption Symfony bundle. Adopt the pattern here, not necessarily the package.