Avro Serde Php Laravel Package

Getting Started

Begin by installing the package via Composer: composer require mateusjunges/avro-serde-php. Next, review the README — it provides a minimal Symfony Serializer setup example. The primary entry point is the AvroSerializer class, which integrates with Symfony’s Serializer component. To serialize/deserialize an object, ensure your schema is defined (e.g., as a JSON file or inline string), load it into an AvroSchema, and pass both the schema and your object to the AvroSerializer. The first common use case is serializing domain objects to Avro binary format for use with Kafka or schema-registries.

Implementation Patterns

• Schema Management: Store Avro schemas in versioned files (e.g., schemas/user.avsc) and load them via AvroSchema::loadJsonFile() or use inline schema strings for simple cases.
• Symfony Integration: Register AvroSerializer as a service and tag it with serializer.normalizer so it integrates with Symfony’s Serializer stack automatically.
• Schema Registry Workflow: Use the included SchemaRegistrySerializer to resolve schema IDs dynamically from a remote registry (e.g., Confluent Schema Registry). Cache schema lookups using Symfony’s Cache component for performance.
• Typed Payloads: Define plain PHP objects (DTOs) with typed properties (public string $name;) and let the serializer handle type conversion and validation based on the Avro schema.
• Testing: Mock the serializer and validate round-trip integrity by deserializing previously serialized binary data; compare domain objects field-by-field.

Gotchas and Tips

• Schema Compatibility: Avro schema resolution is strict by default — mismatches between writer and reader schemas (e.g., missing fields, type mismatches) cause SchemaResolutionException. Use default values and unions (e.g., ["null", "string"]) for forward/backward compatibility.
• Binary vs String Encoding: The serializer outputs raw binary by default. When storing in Kafka, pass false to AvroSerializer::encode() to get binary; when debugging, set true to get base64-encoded strings.
• Performance: Avoid parsing schemas repeatedly — parse once and cache the Schema instance. In long-running processes (e.g., Laravel Horizon jobs), cache schemas in static properties or services.
• PHP 8 Attributes: This package does not use attributes — rely solely on Avro schema definitions. Do not assume annotations or attributes on PHP classes will influence serialization behavior.
• Debugging Errors: Enable AvroSerializer::setLogger() with a PSR-3 logger to capture resolution errors. Check stack traces for schema mismatch details — the error message often includes expected vs actual field names/types.
• Type Coercion: Avro supports coercion (e.g., int → long, string → enum), but PHP strict typing may fail before Avro gets a chance — disable strict types (declare(strict_types=0)) in serializers if integrating with strongly-typed code.