Getting Started

Minimal Setup

Installation:

composer require flix-tech/avro-serde-php

For Symfony projects, also install the serializer bridge:

composer require flix-tech/avro-serde-php-symfony

First Use Case: Define an Avro schema (e.g., user.avsc):

{
  "type": "record",
  "name": "User",
  "fields": [
    {"name": "id", "type": "int"},
    {"name": "name", "type": "string"}
  ]
}

Load and serialize:

use FlixTech\AvroSerde\AvroSerializer;

$serializer = new AvroSerializer();
$schema = $serializer->loadSchemaFromFile(__DIR__.'/user.avsc');

$data = ['id' => 1, 'name' => 'John Doe'];
$binary = $serializer->serialize($data, $schema);

Symfony Integration: Register the serializer in config/services.yaml:

services:
  FlixTech\AvroSerde\Symfony\AvroEncoder:
    arguments:
      - '@avro_serializer'

Use in controllers:

use Symfony\Component\HttpFoundation\JsonResponse;
use FlixTech\AvroSerde\Symfony\AvroEncoder;

public function index(AvroEncoder $encoder): JsonResponse
{
    $data = ['id' => 1, 'name' => 'John Doe'];
    $binary = $encoder->encode($data, $schema);
    return new JsonResponse(['avro' => base64_encode($binary)]);
}

Implementation Patterns

Schema Management

Schema Registry: Store schemas in a central location (e.g., config/avro/schemas/) and load them dynamically:
```
$serializer->loadSchemaFromFile('path/to/schema.avsc');
```

Schema Caching: Cache compiled schemas for performance:

$serializer->setSchemaCache(new \Symfony\Component\Cache\Adapter\FilesystemAdapter());

Data Transformation

Nested Objects: Use Avro’s record and array types for nested structures:

{
  "type": "record",
  "name": "Order",
  "fields": [
    {"name": "user", "type": ["User", {"default": null}]},
    {"name": "items", "type": {"type": "array", "items": "string"}}
  ]
}

Union Types: Handle optional fields with union types:
```
{"type": ["null", "string"]}
```

Integration with Symfony

Request/Response Handling: Use AvroEncoder/AvroDecoder in Symfony’s JsonResponse/JsonRequest:

$request->getContent(); // Binary Avro data
$decoded = $decoder->decode($request->getContent(), $schema);

Serializer Groups: Combine with Symfony’s serializer for hybrid JSON/Avro APIs:

# config/packages/serializer.yaml
FlixTech\AvroSerde\Symfony\AvroEncoder:
    groups: ['avro']

Batch Processing

Streaming: Process large datasets with AvroSerializer::serializeToStream():

$stream = $serializer->serializeToStream($data, $schema);
file_put_contents('output.avro', $stream);

Gotchas and Tips

Common Pitfalls

Schema Validation: Ensure PHP types match Avro types (e.g., int vs. long). Use strictMode: true in config to fail fast:
```
$serializer->setStrictMode(true);
```
Binary Data: Avro binary types (bytes) are serialized as raw bytes. Encode for transport:
```
base64_encode($serializer->serialize($data, $schema));
```

Symfony Circular References: Disable circular reference handling if using Avro (it’s not designed for it):

# config/packages/serializer.yaml
Symfony\Component\Serializer\Normalizer\ObjectNormalizer:
    enable_max_depth: false

Debugging

Schema Errors: Use AvroSerializer::validateSchema() to pre-check schemas:

if (!$serializer->validateSchema($schemaJson)) {
    throw new \RuntimeException('Invalid schema');
}

Binary Inspection: Decode Avro to JSON for debugging:

$decoded = $serializer->deserialize($binaryData, $schema);

Extension Points

Custom Types: Implement FlixTech\AvroSerde\Type\TypeInterface for custom Avro types (e.g., UUIDs):

class UuidType implements TypeInterface {
    public function serialize($value, Schema $schema): string {}
    public function deserialize(string $data, Schema $schema): ?string {}
}

Event Listeners: Hook into serialization/deserialization with Symfony events:

$dispatcher->addListener(
    AvroEvents::PRE_SERIALIZE,
    function ($event) { /* Modify data */ }
);

Performance Tips

Schema Compilation: Pre-compile schemas at boot time:

$serializer->compileSchema($schemaJson); // One-time cost

Memory Management: Use serializeToStream() for large datasets to avoid memory spikes.

Avro Serde Php Laravel Package