diff --git a/composer.json b/composer.json
index ec5d2a3f37b..7069c0edff6 100644
--- a/composer.json
+++ b/composer.json
@@ -23,7 +23,8 @@
     "issues": "https://issues.apache.org/jira/browse/AVRO"
   },
   "require": {
-    "php": "^8.1"
+    "php": "^8.1",
+    "nikic/php-parser": "^5.7"
   },
   "deps": [
     "vendor/phpunit/phpunit"
diff --git a/lang/php/lib/Datum/AvroSpecificDatumWriter.php b/lang/php/lib/Datum/AvroSpecificDatumWriter.php
new file mode 100644
index 00000000000..44c0a21cac1
--- /dev/null
+++ b/lang/php/lib/Datum/AvroSpecificDatumWriter.php
@@ -0,0 +1,236 @@
+<?php
+
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+declare(strict_types=1);
+
+namespace Apache\Avro\Datum;
+
+use Apache\Avro\AvroException;
+use Apache\Avro\Schema\AvroArraySchema;
+use Apache\Avro\Schema\AvroEnumSchema;
+use Apache\Avro\Schema\AvroMapSchema;
+use Apache\Avro\Schema\AvroPrimitiveSchema;
+use Apache\Avro\Schema\AvroRecordSchema;
+use Apache\Avro\Schema\AvroSchema;
+use Apache\Avro\Schema\AvroUnionSchema;
+
+/**
+ * Writes data from code-generated (specific) record classes to the encoder.
+ *
+ * It knows how to extract field values from generated PHP class instances (via getter methods) and backed enum
+ * instances, encoding them according to the Avro schema.
+ *
+ * Generated records expose each field through a getter method whose name matches the Avro field name.
+ * Generated enums are PHP 8.1+ backed string enums whose ->value holds the Avro symbol string.
+ *
+ * Usage:
+ *     $schema  = AvroSchema::parse($json);
+ *     $writer  = new AvroSpecificDatumWriter($schema);
+ *     $io      = new \Apache\Avro\IO\AvroStringIO();
+ *     $encoder = new AvroIOBinaryEncoder($io);
+ *     $writer->write($myGeneratedObject, $encoder);
+ *     $bytes   = $io->string();
+ */
+class AvroSpecificDatumWriter
+{
+    public function __construct(
+        private readonly AvroSchema $writersSchema
+    ) {
+    }
+
+    /**
+     * Serializes the given datum (a generated record instance) to the encoder.
+     *
+     * @throws AvroException
+     */
+    public function write(object $datum, AvroIOBinaryEncoder $encoder): void
+    {
+        $this->writeData($this->writersSchema, $datum, $encoder);
+    }
+
+    /**
+     * @throws AvroException
+     */
+    private function writeData(AvroSchema $schema, mixed $datum, AvroIOBinaryEncoder $encoder): void
+    {
+        match (true) {
+            $schema instanceof AvroRecordSchema => $this->writeRecord($schema, $datum, $encoder),
+            $schema instanceof AvroEnumSchema => $this->writeEnum($schema, $datum, $encoder),
+            $schema instanceof AvroArraySchema => $this->writeArray($schema, $datum, $encoder),
+            $schema instanceof AvroMapSchema => $this->writeMap($schema, $datum, $encoder),
+            $schema instanceof AvroUnionSchema => $this->writeUnion($schema, $datum, $encoder),
+            $schema instanceof AvroPrimitiveSchema => $this->writePrimitive($schema, $datum, $encoder),
+            default => throw new AvroException(sprintf('Unsupported schema type: %s', $schema->type())),
+        };
+    }
+
+    /**
+     * Writes a record by calling the getter for each field defined in the schema.
+     *
+     * @throws AvroException
+     */
+    private function writeRecord(AvroRecordSchema $schema, object $datum, AvroIOBinaryEncoder $encoder): void
+    {
+        foreach ($schema->fields() as $field) {
+            $value = $datum->{$field->name()}();
+            $this->writeData($field->type(), $value, $encoder);
+        }
+    }
+
+    /**
+     * Writes a backed enum value by looking up its symbol index.
+     *
+     * @throws AvroException
+     */
+    private function writeEnum(AvroEnumSchema $schema, \BackedEnum $datum, AvroIOBinaryEncoder $encoder): void
+    {
+        $symbolIndex = $schema->symbolIndex($datum->value);
+        $encoder->writeInt($symbolIndex);
+    }
+
+    /**
+     * @param list<mixed> $datum
+     *
+     * @throws AvroException
+     */
+    private function writeArray(AvroArraySchema $schema, array $datum, AvroIOBinaryEncoder $encoder): void
+    {
+        $count = count($datum);
+        if ($count > 0) {
+            $encoder->writeLong($count);
+            foreach ($datum as $item) {
+                $this->writeData($schema->items(), $item, $encoder);
+            }
+        }
+        $encoder->writeLong(0);
+    }
+
+    /**
+     * @param array<string, mixed> $datum
+     *
+     * @throws AvroException
+     */
+    private function writeMap(AvroMapSchema $schema, array $datum, AvroIOBinaryEncoder $encoder): void
+    {
+        $count = count($datum);
+        if ($count > 0) {
+            $encoder->writeLong($count);
+            foreach ($datum as $key => $value) {
+                $encoder->writeString((string) $key);
+                $this->writeData($schema->values(), $value, $encoder);
+            }
+        }
+        $encoder->writeLong(0);
+    }
+
+    /**
+     * Writes a union value by finding the matching branch schema.
+     *
+     * @throws AvroIOTypeException if no branch matches the datum
+     * @throws AvroException
+     */
+    private function writeUnion(AvroUnionSchema $schema, mixed $datum, AvroIOBinaryEncoder $encoder): void
+    {
+        $matchedIndex = null;
+        $matchedSchema = null;
+
+        foreach ($schema->schemas() as $index => $branchSchema) {
+            if ($this->datumMatchesSchema($branchSchema, $datum)) {
+                $matchedIndex = $index;
+                $matchedSchema = $branchSchema;
+
+                break;
+            }
+        }
+
+        if (null === $matchedSchema) {
+            throw new AvroIOTypeException($schema, $datum);
+        }
+
+        $encoder->writeLong($matchedIndex);
+        $this->writeData($matchedSchema, $datum, $encoder);
+    }
+
+    /**
+     * Writes a primitive value using the appropriate encoder method.
+     *
+     * @throws AvroException
+     */
+    private function writePrimitive(AvroPrimitiveSchema $schema, mixed $datum, AvroIOBinaryEncoder $encoder): void
+    {
+        match ($schema->type()) {
+            AvroSchema::NULL_TYPE => $encoder->writeNull($datum),
+            AvroSchema::BOOLEAN_TYPE => $encoder->writeBoolean($datum),
+            AvroSchema::INT_TYPE => $encoder->writeInt($datum),
+            AvroSchema::LONG_TYPE => $encoder->writeLong($datum),
+            AvroSchema::FLOAT_TYPE => $encoder->writeFloat($datum),
+            AvroSchema::DOUBLE_TYPE => $encoder->writeDouble($datum),
+            AvroSchema::STRING_TYPE => $encoder->writeString($datum),
+            AvroSchema::BYTES_TYPE => $encoder->writeBytes($datum),
+            default => throw new AvroException(sprintf('Unknown primitive type: %s', $schema->type())),
+        };
+    }
+
+    /**
+     * Determines whether the given datum matches the given schema branch.
+     * Used by writeUnion() to find the correct branch index.
+     */
+    private function datumMatchesSchema(AvroSchema $schema, mixed $datum): bool
+    {
+        return match (true) {
+            $schema instanceof AvroPrimitiveSchema => $this->datumMatchesPrimitive($schema, $datum),
+            $schema instanceof AvroEnumSchema => $datum instanceof \BackedEnum
+                && $this->classNameMatchesSchema($datum, $schema->name()),
+            $schema instanceof AvroRecordSchema => is_object($datum)
+                && !($datum instanceof \BackedEnum)
+                && $this->classNameMatchesSchema($datum, $schema->name()),
+            $schema instanceof AvroArraySchema => is_array($datum)
+                && ([] === $datum || array_is_list($datum)),
+            $schema instanceof AvroMapSchema => is_array($datum),
+            default => false,
+        };
+    }
+
+    private function datumMatchesPrimitive(AvroPrimitiveSchema $schema, mixed $datum): bool
+    {
+        return match ($schema->type()) {
+            AvroSchema::NULL_TYPE => null === $datum,
+            AvroSchema::BOOLEAN_TYPE => is_bool($datum),
+            AvroSchema::INT_TYPE => is_int($datum)
+                && $datum >= AvroSchema::INT_MIN_VALUE
+                && $datum <= AvroSchema::INT_MAX_VALUE,
+            AvroSchema::LONG_TYPE => is_int($datum),
+            AvroSchema::FLOAT_TYPE, AvroSchema::DOUBLE_TYPE => is_float($datum) || is_int($datum),
+            AvroSchema::STRING_TYPE, AvroSchema::BYTES_TYPE => is_string($datum),
+            default => false,
+        };
+    }
+
+    /**
+     * Checks whether the short class name of the datum matches the Avro schema name.
+     * Generated classes use ucwords(schemaName) as the class name.
+     */
+    private function classNameMatchesSchema(object $datum, string $schemaName): bool
+    {
+        $className = (new \ReflectionClass($datum))->getShortName();
+
+        return 0 === strcasecmp($className, $schemaName);
+    }
+}
diff --git a/lang/php/lib/Generator/AvroCodeGenerator.php b/lang/php/lib/Generator/AvroCodeGenerator.php
new file mode 100644
index 00000000000..cd12c4c5f73
--- /dev/null
+++ b/lang/php/lib/Generator/AvroCodeGenerator.php
@@ -0,0 +1,374 @@
+<?php
+
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+declare(strict_types=1);
+
+namespace Apache\Avro\Generator;
+
+use Apache\Avro\Schema\AvroArraySchema;
+use Apache\Avro\Schema\AvroEnumSchema;
+use Apache\Avro\Schema\AvroMapSchema;
+use Apache\Avro\Schema\AvroPrimitiveSchema;
+use Apache\Avro\Schema\AvroRecordSchema;
+use Apache\Avro\Schema\AvroSchema;
+use Apache\Avro\Schema\AvroUnionSchema;
+use PhpParser\BuilderFactory;
+use PhpParser\Node;
+use PhpParser\Node\Scalar\String_;
+use PhpParser\Node\Stmt;
+use PhpParser\PrettyPrinter\Standard;
+
+class AvroCodeGenerator
+{
+    private BuilderFactory $factory;
+    private Standard $printer;
+
+    /** @var array<string, AvroSchema> */
+    private array $registry = [];
+
+    public function __construct()
+    {
+        $this->factory = new BuilderFactory();
+        $this->printer = new Standard(['shortArraySyntax' => true]);
+    }
+
+    /**
+     * @return array<string, string> Map of filename to file contents
+     */
+    public function translate(
+        AvroSchema $schema,
+        string $path,
+        string $phpNamespace
+    ): array {
+        $this->buildRegistry($schema);
+
+        $files = [];
+
+        foreach ($this->registry as $name => $registeredSchema) {
+            $node = match (true) {
+                $registeredSchema instanceof AvroEnumSchema => $this->buildEnum(
+                    $registeredSchema,
+                    $phpNamespace,
+                    $registeredSchema->symbols()
+                ),
+                $registeredSchema instanceof AvroRecordSchema => $this->buildRecord(
+                    $registeredSchema,
+                    $phpNamespace
+                ),
+                default => null
+            };
+
+            if (null !== $node) {
+                $code = <<<PHP
+                    <?php
+                    
+                    declare(strict_types=1);
+                    
+                    {$this->printer->prettyPrint([$node])}
+                    
+                    PHP;
+
+                $filename = $path.'/'.ucwords($name).'.php';
+                $files[$filename] = $code;
+            }
+        }
+
+        return $files;
+    }
+
+    private function buildRegistry(AvroSchema $rootSchema): void
+    {
+        $this->registry = [];
+        $this->collectSchemas($rootSchema);
+    }
+
+    private function collectSchemas(AvroSchema $schema): void
+    {
+        switch ($schema::class) {
+            case AvroRecordSchema::class:
+                if (!array_key_exists($schema->fullname(), $this->registry)) {
+                    $this->registry[$schema->fullname()] = $schema;
+                    foreach ($schema->fields() as $field) {
+                        $this->collectSchemas($field->type());
+                    }
+                }
+
+                break;
+            case AvroEnumSchema::class:
+                $this->registry[$schema->fullname()] = $schema;
+
+                break;
+            case AvroArraySchema::class:
+                $this->collectSchemas($schema->items());
+
+                break;
+            case AvroMapSchema::class:
+                $this->collectSchemas($schema->values());
+
+                break;
+            case AvroUnionSchema::class:
+                foreach ($schema->schemas() as $unionSchema) {
+                    $this->collectSchemas($unionSchema);
+                }
+
+                break;
+        }
+    }
+
+    private function buildRecord(
+        AvroRecordSchema $avroRecord,
+        string $phpNamespace
+    ): Node {
+        $className = ucwords($avroRecord->name());
+        $class = $this->factory->class($className)->makeFinal()->implement('\\JsonSerializable');
+
+        foreach ($avroRecord->fields() as $field) {
+            $phpType = $this->avroTypeToPhp($field->type(), $phpNamespace);
+            $property = $this->factory->property($field->name())
+                ->makePrivate()
+                ->setType($phpType);
+
+            $phpDocType = $this->avroTypeToPhpDoc($field->type(), $phpNamespace);
+            if (null !== $phpDocType) {
+                $property->setDocComment('/** @var '.$phpDocType.' */');
+            }
+
+            if ($field->hasDefaultValue()) {
+                $property->setDefault($this->buildDefault($field->defaultValue()));
+            }
+
+            $class->addStmt($property);
+        }
+
+        $constructor = $this->factory->method('__construct')->makePublic();
+        $constructorParamDocs = [];
+        foreach ($avroRecord->fields() as $field) {
+            $phpType = $this->avroTypeToPhp($field->type(), $phpNamespace);
+            $param = $this->factory->param($field->name())->setType($phpType);
+            if ($field->hasDefaultValue()) {
+                $param->setDefault($this->buildDefault($field->defaultValue()));
+            }
+
+            $phpDocType = $this->avroTypeToPhpDoc($field->type(), $phpNamespace);
+            if (null !== $phpDocType) {
+                $constructorParamDocs[] = '@param '.$phpDocType.' $'.$field->name();
+            }
+
+            $constructor->addParam($param);
+            $constructor->addStmt(
+                new Node\Expr\Assign(
+                    new Node\Expr\PropertyFetch(new Node\Expr\Variable('this'), $field->name()),
+                    new Node\Expr\Variable($field->name())
+                )
+            );
+        }
+        if ([] !== $constructorParamDocs) {
+            $docLines = "/**\n";
+            foreach ($constructorParamDocs as $doc) {
+                $docLines .= ' * '.$doc."\n";
+            }
+            $docLines .= ' */';
+            $constructor->setDocComment($docLines);
+        }
+        $class->addStmt($constructor);
+
+        foreach ($avroRecord->fields() as $field) {
+            $phpType = $this->avroTypeToPhp($field->type(), $phpNamespace);
+            $getter = $this->factory->method($field->name())
+                ->makePublic()
+                ->setReturnType($phpType)
+                ->addStmt(
+                    new Stmt\Return_(
+                        new Node\Expr\PropertyFetch(new Node\Expr\Variable('this'), $field->name())
+                    )
+                );
+
+            $phpDocType = $this->avroTypeToPhpDoc($field->type(), $phpNamespace);
+            if (null !== $phpDocType) {
+                $getter->setDocComment('/** @return '.$phpDocType.' */');
+            }
+
+            $class->addStmt($getter);
+        }
+
+        $arrayItems = [];
+        foreach ($avroRecord->fields() as $field) {
+            $arrayItems[] = new Node\ArrayItem(
+                $this->buildJsonSerializeValue($field->type(), $field->name()),
+                new String_($field->name())
+            );
+        }
+        $jsonSerialize = $this->factory->method('jsonSerialize')
+            ->makePublic()
+            ->setReturnType('mixed')
+            ->addStmt(
+                new Stmt\Return_(
+                    new Node\Expr\Array_($arrayItems, ['kind' => Node\Expr\Array_::KIND_SHORT])
+                )
+            );
+        $class->addStmt($jsonSerialize);
+
+        return $this->factory->namespace($phpNamespace)
+            ->addStmt($class)
+            ->getNode();
+    }
+
+    /**
+     * Builds the expression used inside jsonSerialize() for a single field.
+     *
+     * - EnumSchema        → $this->field->value       (plain string for Avro + JSON)
+     * - union[null, Enum] → $this->field?->value      (null-safe, still plain)
+     * - anything else     → $this->field
+     */
+    private function buildJsonSerializeValue(AvroSchema $fieldType, string $fieldName): Node\Expr
+    {
+        $propertyFetch = new Node\Expr\PropertyFetch(new Node\Expr\Variable('this'), $fieldName);
+
+        if ($fieldType instanceof AvroEnumSchema) {
+            return new Node\Expr\PropertyFetch($propertyFetch, 'value');
+        }
+
+        if ($fieldType instanceof AvroUnionSchema) {
+            $nonNullSchemas = array_values(array_filter(
+                $fieldType->schemas(),
+                static fn (AvroSchema $s): bool => !($s instanceof AvroPrimitiveSchema && AvroSchema::NULL_TYPE === $s->type())
+            ));
+
+            if (1 === count($nonNullSchemas) && $nonNullSchemas[0] instanceof AvroEnumSchema) {
+                return new Node\Expr\NullsafePropertyFetch($propertyFetch, 'value');
+            }
+        }
+
+        return $propertyFetch;
+    }
+
+    /**
+     * @param list<string> $values
+     */
+    private function buildEnum(
+        AvroEnumSchema $avroEnum,
+        string $phpNamespace,
+        array $values
+    ): Node {
+        $className = ucwords($avroEnum->name());
+        $enum = $this->factory->enum($className)->setScalarType('string');
+
+        foreach ($values as $value) {
+            $caseName = strtoupper($value);
+            $enum->addStmt(
+                $this->factory->enumCase($caseName)->setValue($value)
+            );
+        }
+
+        return $this->factory->namespace($phpNamespace)
+            ->addStmt($enum)
+            ->getNode();
+    }
+
+    private function avroTypeToPhp(AvroSchema $schema, string $phpNamespace): string
+    {
+        return match (true) {
+            $schema instanceof AvroPrimitiveSchema => $this->avroPrimitiveTypeToPhp($schema),
+            $schema instanceof AvroArraySchema, $schema instanceof AvroMapSchema => 'array',
+            $schema instanceof AvroRecordSchema, $schema instanceof AvroEnumSchema => '\\'.$phpNamespace.'\\'.ucwords($schema->name()),
+            $schema instanceof AvroUnionSchema => $this->unionToPhp($schema, $phpNamespace),
+            default => 'mixed'
+        };
+    }
+
+    private function avroPrimitiveTypeToPhp(AvroPrimitiveSchema $primitiveSchema): string
+    {
+        return match ($primitiveSchema->type()) {
+            AvroSchema::NULL_TYPE => 'null',
+            AvroSchema::BOOLEAN_TYPE => 'bool',
+            AvroSchema::INT_TYPE, AvroSchema::LONG_TYPE => 'int',
+            AvroSchema::FLOAT_TYPE, AvroSchema::DOUBLE_TYPE => 'float',
+            AvroSchema::STRING_TYPE, AvroSchema::BYTES_TYPE => 'string',
+            default => throw new AvroCodeGeneratorException("Unknown primitive type: ".$primitiveSchema->type()),
+        };
+    }
+
+    private function unionToPhp(AvroUnionSchema $union, string $phpNamespace): string
+    {
+        $types = [];
+        foreach ($union->schemas() as $schema) {
+            $types[] = $this->avroTypeToPhp($schema, $phpNamespace);
+        }
+
+        return implode('|', array_unique($types));
+    }
+
+    private function buildDefault(mixed $value): mixed
+    {
+        if (is_array($value)) {
+            return $this->factory->val($value);
+        }
+
+        return $value;
+    }
+
+    /**
+     * Returns a PHPDoc type string for schemas that need richer type info than
+     * what PHP's native type system can express (arrays and maps), or null when
+     * the native type hint is sufficient.
+     */
+    private function avroTypeToPhpDoc(AvroSchema $schema, string $phpNamespace): ?string
+    {
+        return match (true) {
+            $schema instanceof AvroArraySchema => 'list<'.$this->avroTypeToPhpDocInner($schema->items(), $phpNamespace).'>',
+            $schema instanceof AvroMapSchema => 'array<string, '.$this->avroTypeToPhpDocInner($schema->values(), $phpNamespace).'>',
+            $schema instanceof AvroUnionSchema => $this->unionToPhpDoc($schema, $phpNamespace),
+            default => null,
+        };
+    }
+
+    private function avroTypeToPhpDocInner(AvroSchema $schema, string $phpNamespace): string
+    {
+        return match (true) {
+            $schema instanceof AvroPrimitiveSchema => $this->avroPrimitiveTypeToPhp($schema),
+            $schema instanceof AvroArraySchema => 'list<'.$this->avroTypeToPhpDocInner($schema->items(), $phpNamespace).'>',
+            $schema instanceof AvroMapSchema => 'array<string, '.$this->avroTypeToPhpDocInner($schema->values(), $phpNamespace).'>',
+            $schema instanceof AvroRecordSchema, $schema instanceof AvroEnumSchema => '\\'.$phpNamespace.'\\'.ucwords($schema->name()),
+            $schema instanceof AvroUnionSchema => $this->unionToPhp($schema, $phpNamespace),
+            default => 'mixed',
+        };
+    }
+
+    private function unionToPhpDoc(AvroUnionSchema $union, string $phpNamespace): ?string
+    {
+        $hasArrayOrMap = false;
+        $docParts = [];
+
+        foreach ($union->schemas() as $schema) {
+            if ($schema instanceof AvroArraySchema || $schema instanceof AvroMapSchema) {
+                $hasArrayOrMap = true;
+                $docParts[] = $this->avroTypeToPhpDocInner($schema, $phpNamespace);
+            } else {
+                $docParts[] = $this->avroTypeToPhp($schema, $phpNamespace);
+            }
+        }
+
+        if (!$hasArrayOrMap) {
+            return null;
+        }
+
+        return implode('|', array_unique($docParts));
+    }
+}
diff --git a/lang/php/lib/Generator/AvroCodeGeneratorException.php b/lang/php/lib/Generator/AvroCodeGeneratorException.php
new file mode 100644
index 00000000000..5a51754fc3d
--- /dev/null
+++ b/lang/php/lib/Generator/AvroCodeGeneratorException.php
@@ -0,0 +1,27 @@
+<?php
+
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+declare(strict_types=1);
+
+namespace Apache\Avro\Generator;
+
+class AvroCodeGeneratorException extends \Exception
+{
+}
diff --git a/lang/php/lib/Schema/AvroEnumSchema.php b/lang/php/lib/Schema/AvroEnumSchema.php
index 6b6fd12c987..ece163a432e 100644
--- a/lang/php/lib/Schema/AvroEnumSchema.php
+++ b/lang/php/lib/Schema/AvroEnumSchema.php
@@ -62,7 +62,7 @@ public function __construct(AvroName $name, ?string $doc, mixed $symbols, AvroNa
     /**
      * @return string[] this enum schema's symbols
      */
-    public function symbols()
+    public function symbols(): array
     {
         return $this->symbols;
     }
@@ -72,13 +72,14 @@ public function symbols()
      * @return bool true if the given symbol exists in this
      *          enum schema and false otherwise
      */
-    public function hasSymbol($symbol)
+    public function hasSymbol($symbol): bool
     {
         return in_array($symbol, $this->symbols);
     }
 
     /**
      * @param int $index
+     * @throws AvroException
      * @return string enum schema symbol with the given (zero-based) index
      */
     public function symbolByIndex($index)
diff --git a/lang/php/lib/Schema/AvroName.php b/lang/php/lib/Schema/AvroName.php
index 8b8f48b6a8d..a83ff88499d 100644
--- a/lang/php/lib/Schema/AvroName.php
+++ b/lang/php/lib/Schema/AvroName.php
@@ -109,6 +109,11 @@ public function nameAndNamespace(): array
         return [$this->name, $this->namespace];
     }
 
+    public function name(): string
+    {
+        return $this->name;
+    }
+
     public function fullname(): string
     {
         return $this->fullname;
diff --git a/lang/php/lib/Schema/AvroNamedSchema.php b/lang/php/lib/Schema/AvroNamedSchema.php
index b34e90f30ca..29fda82b4cd 100644
--- a/lang/php/lib/Schema/AvroNamedSchema.php
+++ b/lang/php/lib/Schema/AvroNamedSchema.php
@@ -77,6 +77,11 @@ public function toAvro(): string|array
         return $avro;
     }
 
+    public function name(): string
+    {
+        return $this->name->name();
+    }
+
     public function qualifiedName(): string
     {
         return $this->name->qualifiedName();
diff --git a/lang/php/test/Datum/AvroSpecificDatumWriterTest.php b/lang/php/test/Datum/AvroSpecificDatumWriterTest.php
new file mode 100644
index 00000000000..366f3b117e2
--- /dev/null
+++ b/lang/php/test/Datum/AvroSpecificDatumWriterTest.php
@@ -0,0 +1,533 @@
+<?php
+
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+declare(strict_types=1);
+
+namespace Apache\Avro\Tests\Datum;
+
+use Apache\Avro\Datum\AvroIOBinaryDecoder;
+use Apache\Avro\Datum\AvroIOBinaryEncoder;
+use Apache\Avro\Datum\AvroIODatumReader;
+use Apache\Avro\Datum\AvroIODatumWriter;
+use Apache\Avro\Datum\AvroSpecificDatumWriter;
+use Apache\Avro\IO\AvroStringIO;
+use Apache\Avro\Schema\AvroSchema;
+use Apache\Avro\Tests\Fixtures\Generated\Address;
+use Apache\Avro\Tests\Fixtures\Generated\Car;
+use Apache\Avro\Tests\Fixtures\Generated\FuelType;
+use Apache\Avro\Tests\Fixtures\Generated\Member;
+use Apache\Avro\Tests\Fixtures\Generated\Metadata;
+use Apache\Avro\Tests\Fixtures\Generated\Order;
+use Apache\Avro\Tests\Fixtures\Generated\Priority;
+use Apache\Avro\Tests\Fixtures\Generated\Profile;
+use Apache\Avro\Tests\Fixtures\Generated\Task;
+use Apache\Avro\Tests\Fixtures\Generated\Team;
+use Apache\Avro\Tests\Fixtures\Generated\User;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * Tests for AvroSpecificDatumWriter: serializing generated class instances
+ * to Avro binary and verifying round-trip via AvroIODatumReader.
+ */
+class AvroSpecificDatumWriterTest extends TestCase
+{
+    #[Test]
+    public function simple_record_with_primitives(): void
+    {
+        $schema = AvroSchema::parse(<<<JSON
+            {
+                "type": "record",
+                "name": "User",
+                "fields": [
+                    {"name": "name", "type": "string"},
+                    {"name": "age", "type": "int"},
+                    {"name": "active", "type": "boolean"},
+                    {"name": "score", "type": "float"}
+                ]
+            }
+            JSON);
+
+        $user = new User('Alice', 30, true, 9.5);
+        $result = $this->roundTrip($schema, $user);
+
+        self::assertSame('Alice', $result['name']);
+        self::assertSame(30, $result['age']);
+        self::assertTrue($result['active']);
+        self::assertEqualsWithDelta(9.5, $result['score'], 0.001);
+    }
+
+    #[Test]
+    public function record_with_enum_field(): void
+    {
+        $schema = AvroSchema::parse(<<<JSON
+            {
+                "type": "record",
+                "name": "Car",
+                "fields": [
+                    {"name": "brand", "type": "string"},
+                    {
+                        "name": "fuel",
+                        "type": {
+                            "type": "enum",
+                            "name": "FuelType",
+                            "symbols": ["gasoline", "diesel", "electric"]
+                        }
+                    }
+                ]
+            }
+            JSON);
+
+        $car = new Car('Tesla', FuelType::ELECTRIC);
+        $result = $this->roundTrip($schema, $car);
+
+        self::assertSame('Tesla', $result['brand']);
+        self::assertSame('electric', $result['fuel']);
+    }
+
+    #[Test]
+    public function record_with_nested_record(): void
+    {
+        $schema = AvroSchema::parse(<<<JSON
+            {
+                "type": "record",
+                "name": "Order",
+                "fields": [
+                    {"name": "id", "type": "int"},
+                    {
+                        "name": "address",
+                        "type": {
+                            "type": "record",
+                            "name": "Address",
+                            "fields": [
+                                {"name": "street", "type": "string"},
+                                {"name": "city", "type": "string"}
+                            ]
+                        }
+                    }
+                ]
+            }
+            JSON);
+
+        $order = new Order(42, new Address('123 Main St', 'Springfield'));
+        $result = $this->roundTrip($schema, $order);
+
+        self::assertSame(42, $result['id']);
+        self::assertSame('123 Main St', $result['address']['street']);
+        self::assertSame('Springfield', $result['address']['city']);
+    }
+
+    #[Test]
+    public function record_with_nullable_field_present(): void
+    {
+        $schema = AvroSchema::parse(<<<JSON
+            {
+                "type": "record",
+                "name": "Profile",
+                "fields": [
+                    {"name": "username", "type": "string"},
+                    {"name": "bio", "type": ["null", "string"], "default": null}
+                ]
+            }
+            JSON);
+
+        $profile = new Profile('bob', 'Hello world');
+        $result = $this->roundTrip($schema, $profile);
+
+        self::assertSame('bob', $result['username']);
+        self::assertSame('Hello world', $result['bio']);
+    }
+
+    #[Test]
+    public function record_with_nullable_field_null(): void
+    {
+        $schema = AvroSchema::parse(<<<JSON
+            {
+                "type": "record",
+                "name": "Profile",
+                "fields": [
+                    {"name": "username", "type": "string"},
+                    {"name": "bio", "type": ["null", "string"], "default": null}
+                ]
+            }
+            JSON);
+
+        $profile = new Profile('bob');
+        $result = $this->roundTrip($schema, $profile);
+
+        self::assertSame('bob', $result['username']);
+        self::assertNull($result['bio']);
+    }
+
+    #[Test]
+    public function record_with_nullable_enum_present(): void
+    {
+        $schema = AvroSchema::parse(<<<JSON
+            {
+                "type": "record",
+                "name": "Task",
+                "fields": [
+                    {"name": "title", "type": "string"},
+                    {
+                        "name": "priority",
+                        "type": [
+                            "null",
+                            {
+                                "type": "enum",
+                                "name": "Priority",
+                                "symbols": ["low", "medium", "high"]
+                            }
+                        ],
+                        "default": null
+                    }
+                ]
+            }
+            JSON);
+
+        $task = new Task('Fix bug', Priority::HIGH);
+        $result = $this->roundTrip($schema, $task);
+
+        self::assertSame('Fix bug', $result['title']);
+        self::assertSame('high', $result['priority']);
+    }
+
+    #[Test]
+    public function record_with_nullable_enum_null(): void
+    {
+        $schema = AvroSchema::parse(<<<JSON
+            {
+                "type": "record",
+                "name": "Task",
+                "fields": [
+                    {"name": "title", "type": "string"},
+                    {
+                        "name": "priority",
+                        "type": [
+                            "null",
+                            {
+                                "type": "enum",
+                                "name": "Priority",
+                                "symbols": ["low", "medium", "high"]
+                            }
+                        ],
+                        "default": null
+                    }
+                ]
+            }
+            JSON);
+
+        $task = new Task('No priority');
+        $result = $this->roundTrip($schema, $task);
+
+        self::assertSame('No priority', $result['title']);
+        self::assertNull($result['priority']);
+    }
+
+    #[Test]
+    public function record_with_array_of_records(): void
+    {
+        $schema = AvroSchema::parse(<<<JSON
+            {
+                "type": "record",
+                "name": "Team",
+                "fields": [
+                    {"name": "name", "type": "string"},
+                    {
+                        "name": "members",
+                        "type": {
+                            "type": "array",
+                            "items": {
+                                "type": "record",
+                                "name": "Member",
+                                "fields": [
+                                    {"name": "name", "type": "string"},
+                                    {"name": "role", "type": "string"}
+                                ]
+                            }
+                        }
+                    }
+                ]
+            }
+            JSON);
+
+        $team = new Team('Engineering', [
+            new Member('Alice', 'Lead'),
+            new Member('Bob', 'Developer'),
+        ]);
+        $result = $this->roundTrip($schema, $team);
+
+        self::assertSame('Engineering', $result['name']);
+        self::assertCount(2, $result['members']);
+        self::assertSame('Alice', $result['members'][0]['name']);
+        self::assertSame('Lead', $result['members'][0]['role']);
+        self::assertSame('Bob', $result['members'][1]['name']);
+        self::assertSame('Developer', $result['members'][1]['role']);
+    }
+
+    #[Test]
+    public function record_with_empty_array(): void
+    {
+        $schema = AvroSchema::parse(<<<JSON
+            {
+                "type": "record",
+                "name": "Team",
+                "fields": [
+                    {"name": "name", "type": "string"},
+                    {
+                        "name": "members",
+                        "type": {
+                            "type": "array",
+                            "items": {
+                                "type": "record",
+                                "name": "Member",
+                                "fields": [
+                                    {"name": "name", "type": "string"},
+                                    {"name": "role", "type": "string"}
+                                ]
+                            }
+                        }
+                    }
+                ]
+            }
+            JSON);
+
+        $team = new Team('Empty Team', []);
+        $result = $this->roundTrip($schema, $team);
+
+        self::assertSame('Empty Team', $result['name']);
+        self::assertSame([], $result['members']);
+    }
+
+    #[Test]
+    public function record_with_map_field(): void
+    {
+        $schema = AvroSchema::parse(<<<JSON
+            {
+                "type": "record",
+                "name": "Metadata",
+                "fields": [
+                    {"name": "properties", "type": {"type": "map", "values": "string"}}
+                ]
+            }
+            JSON);
+
+        $metadata = new Metadata(['env' => 'production', 'version' => '1.2.3']);
+        $result = $this->roundTrip($schema, $metadata);
+
+        self::assertSame('production', $result['properties']['env']);
+        self::assertSame('1.2.3', $result['properties']['version']);
+    }
+
+    #[Test]
+    public function record_with_empty_map(): void
+    {
+        $schema = AvroSchema::parse(<<<JSON
+            {
+                "type": "record",
+                "name": "Metadata",
+                "fields": [
+                    {"name": "properties", "type": {"type": "map", "values": "string"}}
+                ]
+            }
+            JSON);
+
+        $metadata = new Metadata([]);
+        $result = $this->roundTrip($schema, $metadata);
+
+        self::assertSame([], $result['properties']);
+    }
+
+    #[Test]
+    public function produces_same_bytes_as_generic_writer(): void
+    {
+        $schema = AvroSchema::parse(<<<JSON
+            {
+                "type": "record",
+                "name": "User",
+                "fields": [
+                    {"name": "name", "type": "string"},
+                    {"name": "age", "type": "int"},
+                    {"name": "active", "type": "boolean"},
+                    {"name": "score", "type": "float"}
+                ]
+            }
+            JSON);
+
+        // Specific writer: from object
+        $user = new User('Alice', 30, true, 9.5);
+        $specificWriter = new AvroSpecificDatumWriter($schema);
+        $specificIo = new AvroStringIO();
+        $specificEncoder = new AvroIOBinaryEncoder($specificIo);
+        $specificWriter->write($user, $specificEncoder);
+
+        // Generic writer: from associative array
+        $genericWriter = new AvroIODatumWriter($schema);
+        $genericIo = new AvroStringIO();
+        $genericEncoder = new AvroIOBinaryEncoder($genericIo);
+        $genericWriter->write(
+            ['name' => 'Alice', 'age' => 30, 'active' => true, 'score' => 9.5],
+            $genericEncoder
+        );
+
+        self::assertSame($genericIo->string(), $specificIo->string());
+    }
+
+    #[Test]
+    public function produces_same_bytes_for_enum_as_generic_writer(): void
+    {
+        $schema = AvroSchema::parse(<<<JSON
+            {
+                "type": "record",
+                "name": "Car",
+                "fields": [
+                    {"name": "brand", "type": "string"},
+                    {
+                        "name": "fuel",
+                        "type": {
+                            "type": "enum",
+                            "name": "FuelType",
+                            "symbols": ["gasoline", "diesel", "electric"]
+                        }
+                    }
+                ]
+            }
+            JSON);
+
+        // Specific
+        $car = new Car('BMW', FuelType::DIESEL);
+        $specificWriter = new AvroSpecificDatumWriter($schema);
+        $specificIo = new AvroStringIO();
+        $specificWriter->write($car, new AvroIOBinaryEncoder($specificIo));
+
+        // Generic
+        $genericWriter = new AvroIODatumWriter($schema);
+        $genericIo = new AvroStringIO();
+        $genericWriter->write(
+            ['brand' => 'BMW', 'fuel' => 'diesel'],
+            new AvroIOBinaryEncoder($genericIo)
+        );
+
+        self::assertSame($genericIo->string(), $specificIo->string());
+    }
+
+    #[Test]
+    public function produces_same_bytes_for_nested_record_as_generic_writer(): void
+    {
+        $schema = AvroSchema::parse(<<<JSON
+            {
+                "type": "record",
+                "name": "Order",
+                "fields": [
+                    {"name": "id", "type": "int"},
+                    {
+                        "name": "address",
+                        "type": {
+                            "type": "record",
+                            "name": "Address",
+                            "fields": [
+                                {"name": "street", "type": "string"},
+                                {"name": "city", "type": "string"}
+                            ]
+                        }
+                    }
+                ]
+            }
+            JSON);
+
+        // Specific
+        $order = new Order(99, new Address('Oak Ave', 'Riverside'));
+        $specificWriter = new AvroSpecificDatumWriter($schema);
+        $specificIo = new AvroStringIO();
+        $specificWriter->write($order, new AvroIOBinaryEncoder($specificIo));
+
+        // Generic
+        $genericWriter = new AvroIODatumWriter($schema);
+        $genericIo = new AvroStringIO();
+        $genericWriter->write(
+            ['id' => 99, 'address' => ['street' => 'Oak Ave', 'city' => 'Riverside']],
+            new AvroIOBinaryEncoder($genericIo)
+        );
+
+        self::assertSame($genericIo->string(), $specificIo->string());
+    }
+
+    #[Test]
+    public function produces_same_bytes_for_nullable_union_as_generic_writer(): void
+    {
+        $schema = AvroSchema::parse(<<<JSON
+            {
+                "type": "record",
+                "name": "Profile",
+                "fields": [
+                    {"name": "username", "type": "string"},
+                    {"name": "bio", "type": ["null", "string"], "default": null}
+                ]
+            }
+            JSON);
+
+        // With value
+        $profile = new Profile('alice', 'Bio text');
+        $specificWriter = new AvroSpecificDatumWriter($schema);
+        $specificIo = new AvroStringIO();
+        $specificWriter->write($profile, new AvroIOBinaryEncoder($specificIo));
+
+        $genericWriter = new AvroIODatumWriter($schema);
+        $genericIo = new AvroStringIO();
+        $genericWriter->write(
+            ['username' => 'alice', 'bio' => 'Bio text'],
+            new AvroIOBinaryEncoder($genericIo)
+        );
+
+        self::assertSame($genericIo->string(), $specificIo->string());
+
+        // With null
+        $profileNull = new Profile('bob');
+        $specificIo2 = new AvroStringIO();
+        $specificWriter->write($profileNull, new AvroIOBinaryEncoder($specificIo2));
+
+        $genericIo2 = new AvroStringIO();
+        $genericWriter->write(
+            ['username' => 'bob', 'bio' => null],
+            new AvroIOBinaryEncoder($genericIo2)
+        );
+
+        self::assertSame($genericIo2->string(), $specificIo2->string());
+    }
+
+    /**
+     * Helper: serialize with AvroSpecificDatumWriter, then deserialize
+     * with AvroIODatumReader to get back an associative array.
+     */
+    private function roundTrip(AvroSchema $schema, object $datum): mixed
+    {
+        // Serialize
+        $writer = new AvroSpecificDatumWriter($schema);
+        $io = new AvroStringIO();
+        $encoder = new AvroIOBinaryEncoder($io);
+        $writer->write($datum, $encoder);
+
+        // Deserialize
+        $io->seek(0);
+        $reader = new AvroIODatumReader($schema);
+        $decoder = new AvroIOBinaryDecoder($io);
+
+        return $reader->read($decoder);
+    }
+}
diff --git a/lang/php/test/Fixtures/Generated/Address.php b/lang/php/test/Fixtures/Generated/Address.php
new file mode 100644
index 00000000000..1f2abb7985d
--- /dev/null
+++ b/lang/php/test/Fixtures/Generated/Address.php
@@ -0,0 +1,50 @@
+<?php
+
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+declare(strict_types=1);
+
+namespace Apache\Avro\Tests\Fixtures\Generated;
+
+final class Address implements \JsonSerializable
+{
+    private string $street;
+    private string $city;
+
+    public function __construct(string $street, string $city)
+    {
+        $this->street = $street;
+        $this->city = $city;
+    }
+
+    public function street(): string
+    {
+        return $this->street;
+    }
+
+    public function city(): string
+    {
+        return $this->city;
+    }
+
+    public function jsonSerialize(): mixed
+    {
+        return ['street' => $this->street, 'city' => $this->city];
+    }
+}
diff --git a/lang/php/test/Fixtures/Generated/Car.php b/lang/php/test/Fixtures/Generated/Car.php
new file mode 100644
index 00000000000..d9e223aa770
--- /dev/null
+++ b/lang/php/test/Fixtures/Generated/Car.php
@@ -0,0 +1,50 @@
+<?php
+
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+declare(strict_types=1);
+
+namespace Apache\Avro\Tests\Fixtures\Generated;
+
+final class Car implements \JsonSerializable
+{
+    private string $brand;
+    private FuelType $fuel;
+
+    public function __construct(string $brand, FuelType $fuel)
+    {
+        $this->brand = $brand;
+        $this->fuel = $fuel;
+    }
+
+    public function brand(): string
+    {
+        return $this->brand;
+    }
+
+    public function fuel(): FuelType
+    {
+        return $this->fuel;
+    }
+
+    public function jsonSerialize(): mixed
+    {
+        return ['brand' => $this->brand, 'fuel' => $this->fuel->value];
+    }
+}
diff --git a/lang/php/test/Fixtures/Generated/FuelType.php b/lang/php/test/Fixtures/Generated/FuelType.php
new file mode 100644
index 00000000000..5ca9cbdd87a
--- /dev/null
+++ b/lang/php/test/Fixtures/Generated/FuelType.php
@@ -0,0 +1,30 @@
+<?php
+
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+declare(strict_types=1);
+
+namespace Apache\Avro\Tests\Fixtures\Generated;
+
+enum FuelType: string
+{
+    case GASOLINE = 'gasoline';
+    case DIESEL = 'diesel';
+    case ELECTRIC = 'electric';
+}
diff --git a/lang/php/test/Fixtures/Generated/Member.php b/lang/php/test/Fixtures/Generated/Member.php
new file mode 100644
index 00000000000..fff64c2ec69
--- /dev/null
+++ b/lang/php/test/Fixtures/Generated/Member.php
@@ -0,0 +1,50 @@
+<?php
+
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+declare(strict_types=1);
+
+namespace Apache\Avro\Tests\Fixtures\Generated;
+
+final class Member implements \JsonSerializable
+{
+    private string $name;
+    private string $role;
+
+    public function __construct(string $name, string $role)
+    {
+        $this->name = $name;
+        $this->role = $role;
+    }
+
+    public function name(): string
+    {
+        return $this->name;
+    }
+
+    public function role(): string
+    {
+        return $this->role;
+    }
+
+    public function jsonSerialize(): mixed
+    {
+        return ['name' => $this->name, 'role' => $this->role];
+    }
+}
diff --git a/lang/php/test/Fixtures/Generated/Metadata.php b/lang/php/test/Fixtures/Generated/Metadata.php
new file mode 100644
index 00000000000..4c91b566952
--- /dev/null
+++ b/lang/php/test/Fixtures/Generated/Metadata.php
@@ -0,0 +1,48 @@
+<?php
+
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+declare(strict_types=1);
+
+namespace Apache\Avro\Tests\Fixtures\Generated;
+
+final class Metadata implements \JsonSerializable
+{
+    /** @var array<string, string> */
+    private array $properties;
+
+    /**
+     * @param array<string, string> $properties
+     */
+    public function __construct(array $properties)
+    {
+        $this->properties = $properties;
+    }
+
+    /** @return array<string, string> */
+    public function properties(): array
+    {
+        return $this->properties;
+    }
+
+    public function jsonSerialize(): mixed
+    {
+        return ['properties' => $this->properties];
+    }
+}
diff --git a/lang/php/test/Fixtures/Generated/Order.php b/lang/php/test/Fixtures/Generated/Order.php
new file mode 100644
index 00000000000..b4fee35c8fe
--- /dev/null
+++ b/lang/php/test/Fixtures/Generated/Order.php
@@ -0,0 +1,50 @@
+<?php
+
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+declare(strict_types=1);
+
+namespace Apache\Avro\Tests\Fixtures\Generated;
+
+final class Order implements \JsonSerializable
+{
+    private int $id;
+    private Address $address;
+
+    public function __construct(int $id, Address $address)
+    {
+        $this->id = $id;
+        $this->address = $address;
+    }
+
+    public function id(): int
+    {
+        return $this->id;
+    }
+
+    public function address(): Address
+    {
+        return $this->address;
+    }
+
+    public function jsonSerialize(): mixed
+    {
+        return ['id' => $this->id, 'address' => $this->address];
+    }
+}
diff --git a/lang/php/test/Fixtures/Generated/Priority.php b/lang/php/test/Fixtures/Generated/Priority.php
new file mode 100644
index 00000000000..34b7f1d5823
--- /dev/null
+++ b/lang/php/test/Fixtures/Generated/Priority.php
@@ -0,0 +1,30 @@
+<?php
+
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+declare(strict_types=1);
+
+namespace Apache\Avro\Tests\Fixtures\Generated;
+
+enum Priority: string
+{
+    case LOW = 'low';
+    case MEDIUM = 'medium';
+    case HIGH = 'high';
+}
diff --git a/lang/php/test/Fixtures/Generated/Profile.php b/lang/php/test/Fixtures/Generated/Profile.php
new file mode 100644
index 00000000000..42f002df6c6
--- /dev/null
+++ b/lang/php/test/Fixtures/Generated/Profile.php
@@ -0,0 +1,50 @@
+<?php
+
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+declare(strict_types=1);
+
+namespace Apache\Avro\Tests\Fixtures\Generated;
+
+final class Profile implements \JsonSerializable
+{
+    private string $username;
+    private ?string $bio;
+
+    public function __construct(string $username, ?string $bio = null)
+    {
+        $this->username = $username;
+        $this->bio = $bio;
+    }
+
+    public function username(): string
+    {
+        return $this->username;
+    }
+
+    public function bio(): ?string
+    {
+        return $this->bio;
+    }
+
+    public function jsonSerialize(): mixed
+    {
+        return ['username' => $this->username, 'bio' => $this->bio];
+    }
+}
diff --git a/lang/php/test/Fixtures/Generated/Task.php b/lang/php/test/Fixtures/Generated/Task.php
new file mode 100644
index 00000000000..60adfb44a89
--- /dev/null
+++ b/lang/php/test/Fixtures/Generated/Task.php
@@ -0,0 +1,50 @@
+<?php
+
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+declare(strict_types=1);
+
+namespace Apache\Avro\Tests\Fixtures\Generated;
+
+final class Task implements \JsonSerializable
+{
+    private string $title;
+    private ?Priority $priority;
+
+    public function __construct(string $title, ?Priority $priority = null)
+    {
+        $this->title = $title;
+        $this->priority = $priority;
+    }
+
+    public function title(): string
+    {
+        return $this->title;
+    }
+
+    public function priority(): ?Priority
+    {
+        return $this->priority;
+    }
+
+    public function jsonSerialize(): mixed
+    {
+        return ['title' => $this->title, 'priority' => $this->priority?->value];
+    }
+}
diff --git a/lang/php/test/Fixtures/Generated/Team.php b/lang/php/test/Fixtures/Generated/Team.php
new file mode 100644
index 00000000000..1d16dfa9c51
--- /dev/null
+++ b/lang/php/test/Fixtures/Generated/Team.php
@@ -0,0 +1,55 @@
+<?php
+
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+declare(strict_types=1);
+
+namespace Apache\Avro\Tests\Fixtures\Generated;
+
+final class Team implements \JsonSerializable
+{
+    private string $name;
+    /** @var list<Member> */
+    private array $members;
+
+    /**
+     * @param list<Member> $members
+     */
+    public function __construct(string $name, array $members)
+    {
+        $this->name = $name;
+        $this->members = $members;
+    }
+
+    public function name(): string
+    {
+        return $this->name;
+    }
+
+    /** @return list<Member> */
+    public function members(): array
+    {
+        return $this->members;
+    }
+
+    public function jsonSerialize(): mixed
+    {
+        return ['name' => $this->name, 'members' => $this->members];
+    }
+}
diff --git a/lang/php/test/Fixtures/Generated/User.php b/lang/php/test/Fixtures/Generated/User.php
new file mode 100644
index 00000000000..b328ebbd627
--- /dev/null
+++ b/lang/php/test/Fixtures/Generated/User.php
@@ -0,0 +1,64 @@
+<?php
+
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+declare(strict_types=1);
+
+namespace Apache\Avro\Tests\Fixtures\Generated;
+
+final class User implements \JsonSerializable
+{
+    private string $name;
+    private int $age;
+    private bool $active;
+    private float $score;
+
+    public function __construct(string $name, int $age, bool $active, float $score)
+    {
+        $this->name = $name;
+        $this->age = $age;
+        $this->active = $active;
+        $this->score = $score;
+    }
+
+    public function name(): string
+    {
+        return $this->name;
+    }
+
+    public function age(): int
+    {
+        return $this->age;
+    }
+
+    public function active(): bool
+    {
+        return $this->active;
+    }
+
+    public function score(): float
+    {
+        return $this->score;
+    }
+
+    public function jsonSerialize(): mixed
+    {
+        return ['name' => $this->name, 'age' => $this->age, 'active' => $this->active, 'score' => $this->score];
+    }
+}
diff --git a/lang/php/test/Generator/AvroCodeGeneratorTest.php b/lang/php/test/Generator/AvroCodeGeneratorTest.php
new file mode 100644
index 00000000000..8473727795f
--- /dev/null
+++ b/lang/php/test/Generator/AvroCodeGeneratorTest.php
@@ -0,0 +1,1677 @@
+<?php
+
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+declare(strict_types=1);
+
+namespace Apache\Avro\Tests\Generator;
+
+use Apache\Avro\Generator\AvroCodeGenerator;
+use Apache\Avro\Schema\AvroSchema;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+
+class AvroCodeGeneratorTest extends TestCase
+{
+    private AvroCodeGenerator $transpiler;
+
+    public function setUp(): void
+    {
+        $this->transpiler = new AvroCodeGenerator();
+    }
+
+    #[Test]
+    public function nested_schema_generation(): void
+    {
+        $schema = <<<JSON
+            {
+               "type":"record",
+               "name":"Lisp",
+               "fields":[
+                  {
+                     "name":"value",
+                     "type":[
+                        "null",
+                        "string",
+                        {
+                           "type":"record",
+                           "name":"Cons",
+                           "fields":[
+                              {
+                                 "name":"car",
+                                 "type":"Lisp"
+                              },
+                              {
+                                 "name":"cdr",
+                                 "type":"Lisp"
+                              }
+                           ]
+                        }
+                     ]
+                  }
+               ]
+            }
+            JSON;
+
+        $avroSchema = AvroSchema::parse($schema);
+        $files = $this->transpiler->translate($avroSchema, '/generated', 'MyApp\\Avro\\Generated');
+
+        self::assertCount(2, $files);
+
+        self::assertArrayHasKey('/generated/Lisp.php', $files);
+        self::assertArrayHasKey('/generated/Cons.php', $files);
+
+        $expectedLisp = <<<PHP
+            <?php
+            
+            declare(strict_types=1);
+            
+            namespace MyApp\Avro\Generated;
+            
+            final class Lisp implements \JsonSerializable
+            {
+                private null|string|\MyApp\Avro\Generated\Cons \$value;
+                public function __construct(null|string|\MyApp\Avro\Generated\Cons \$value)
+                {
+                    \$this->value = \$value;
+                }
+                public function value(): null|string|\MyApp\Avro\Generated\Cons
+                {
+                    return \$this->value;
+                }
+                public function jsonSerialize(): mixed
+                {
+                    return ['value' => \$this->value];
+                }
+            }
+
+            PHP;
+
+        self::assertEquals($expectedLisp, $files['/generated/Lisp.php']);
+
+        $expectedLisp = <<<PHP
+            <?php
+
+            declare(strict_types=1);
+            
+            namespace MyApp\Avro\Generated;
+            
+            final class Cons implements \JsonSerializable
+            {
+                private \MyApp\Avro\Generated\Lisp \$car;
+                private \MyApp\Avro\Generated\Lisp \$cdr;
+                public function __construct(\MyApp\Avro\Generated\Lisp \$car, \MyApp\Avro\Generated\Lisp \$cdr)
+                {
+                    \$this->car = \$car;
+                    \$this->cdr = \$cdr;
+                }
+                public function car(): \MyApp\Avro\Generated\Lisp
+                {
+                    return \$this->car;
+                }
+                public function cdr(): \MyApp\Avro\Generated\Lisp
+                {
+                    return \$this->cdr;
+                }
+                public function jsonSerialize(): mixed
+                {
+                    return ['car' => \$this->car, 'cdr' => \$this->cdr];
+                }
+            }
+
+            PHP;
+        self::assertEquals($expectedLisp, $files['/generated/Cons.php']);
+    }
+
+    #[Test]
+    public function simple_record_with_primitive_types(): void
+    {
+        $schema = <<<JSON
+            {
+                "type": "record",
+                "name": "User",
+                "fields": [
+                    {"name": "name", "type": "string"},
+                    {"name": "age", "type": "int"},
+                    {"name": "active", "type": "boolean"},
+                    {"name": "score", "type": "float"}
+                ]
+            }
+            JSON;
+
+        $avroSchema = AvroSchema::parse($schema);
+        $files = $this->transpiler->translate($avroSchema, '/generated', 'App\\Model');
+
+        self::assertCount(1, $files);
+        self::assertArrayHasKey('/generated/User.php', $files);
+
+        $expected = <<<PHP
+            <?php
+            
+            declare(strict_types=1);
+            
+            namespace App\Model;
+            
+            final class User implements \JsonSerializable
+            {
+                private string \$name;
+                private int \$age;
+                private bool \$active;
+                private float \$score;
+                public function __construct(string \$name, int \$age, bool \$active, float \$score)
+                {
+                    \$this->name = \$name;
+                    \$this->age = \$age;
+                    \$this->active = \$active;
+                    \$this->score = \$score;
+                }
+                public function name(): string
+                {
+                    return \$this->name;
+                }
+                public function age(): int
+                {
+                    return \$this->age;
+                }
+                public function active(): bool
+                {
+                    return \$this->active;
+                }
+                public function score(): float
+                {
+                    return \$this->score;
+                }
+                public function jsonSerialize(): mixed
+                {
+                    return ['name' => \$this->name, 'age' => \$this->age, 'active' => \$this->active, 'score' => \$this->score];
+                }
+            }
+
+            PHP;
+
+        self::assertEquals($expected, $files['/generated/User.php']);
+    }
+
+    #[Test]
+    public function enum_schema_generation(): void
+    {
+        $schema = <<<JSON
+            {
+                "type": "enum",
+                "name": "Color",
+                "symbols": ["red", "green", "blue"]
+            }
+            JSON;
+
+        $avroSchema = AvroSchema::parse($schema);
+        $files = $this->transpiler->translate($avroSchema, '/generated', 'App\\Enums');
+
+        self::assertCount(1, $files);
+        self::assertArrayHasKey('/generated/Color.php', $files);
+
+        $expected = <<<PHP
+            <?php
+            
+            declare(strict_types=1);
+            
+            namespace App\Enums;
+            
+            enum Color : string
+            {
+                case RED = 'red';
+                case GREEN = 'green';
+                case BLUE = 'blue';
+            }
+
+            PHP;
+
+        self::assertEquals($expected, $files['/generated/Color.php']);
+    }
+
+    #[Test]
+    public function record_with_default_values(): void
+    {
+        $schema = <<<JSON
+            {
+                "type": "record",
+                "name": "Config",
+                "fields": [
+                    {"name": "retries", "type": "int", "default": 3},
+                    {"name": "label", "type": "string", "default": "default"},
+                    {"name": "enabled", "type": "boolean", "default": true}
+                ]
+            }
+            JSON;
+
+        $avroSchema = AvroSchema::parse($schema);
+        $files = $this->transpiler->translate($avroSchema, '/generated', 'App\\Config');
+
+        self::assertCount(1, $files);
+        self::assertArrayHasKey('/generated/Config.php', $files);
+
+        $expected = <<<PHP
+            <?php
+            
+            declare(strict_types=1);
+            
+            namespace App\Config;
+            
+            final class Config implements \JsonSerializable
+            {
+                private int \$retries = 3;
+                private string \$label = 'default';
+                private bool \$enabled = true;
+                public function __construct(int \$retries = 3, string \$label = 'default', bool \$enabled = true)
+                {
+                    \$this->retries = \$retries;
+                    \$this->label = \$label;
+                    \$this->enabled = \$enabled;
+                }
+                public function retries(): int
+                {
+                    return \$this->retries;
+                }
+                public function label(): string
+                {
+                    return \$this->label;
+                }
+                public function enabled(): bool
+                {
+                    return \$this->enabled;
+                }
+                public function jsonSerialize(): mixed
+                {
+                    return ['retries' => \$this->retries, 'label' => \$this->label, 'enabled' => \$this->enabled];
+                }
+            }
+
+            PHP;
+
+        self::assertEquals($expected, $files['/generated/Config.php']);
+    }
+
+    #[Test]
+    public function record_with_array_field(): void
+    {
+        $schema = <<<JSON
+            {
+                "type": "record",
+                "name": "Playlist",
+                "fields": [
+                    {"name": "name", "type": "string"},
+                    {"name": "tags", "type": {"type": "array", "items": "string"}}
+                ]
+            }
+            JSON;
+
+        $avroSchema = AvroSchema::parse($schema);
+        $files = $this->transpiler->translate($avroSchema, '/generated', 'App\\Music');
+
+        self::assertCount(1, $files);
+        self::assertArrayHasKey('/generated/Playlist.php', $files);
+
+        $expected = <<<PHP
+            <?php
+            
+            declare(strict_types=1);
+            
+            namespace App\Music;
+            
+            final class Playlist implements \JsonSerializable
+            {
+                private string \$name;
+                /** @var list<string> */
+                private array \$tags;
+                /**
+                 * @param list<string> \$tags
+                 */
+                public function __construct(string \$name, array \$tags)
+                {
+                    \$this->name = \$name;
+                    \$this->tags = \$tags;
+                }
+                public function name(): string
+                {
+                    return \$this->name;
+                }
+                /** @return list<string> */
+                public function tags(): array
+                {
+                    return \$this->tags;
+                }
+                public function jsonSerialize(): mixed
+                {
+                    return ['name' => \$this->name, 'tags' => \$this->tags];
+                }
+            }
+
+            PHP;
+
+        self::assertEquals($expected, $files['/generated/Playlist.php']);
+    }
+
+    #[Test]
+    public function record_with_map_field(): void
+    {
+        $schema = <<<JSON
+            {
+                "type": "record",
+                "name": "Metadata",
+                "fields": [
+                    {"name": "properties", "type": {"type": "map", "values": "string"}}
+                ]
+            }
+            JSON;
+
+        $avroSchema = AvroSchema::parse($schema);
+        $files = $this->transpiler->translate($avroSchema, '/generated', 'App\\Data');
+
+        self::assertCount(1, $files);
+        self::assertArrayHasKey('/generated/Metadata.php', $files);
+
+        $expected = <<<PHP
+            <?php
+            
+            declare(strict_types=1);
+            
+            namespace App\Data;
+            
+            final class Metadata implements \JsonSerializable
+            {
+                /** @var array<string, string> */
+                private array \$properties;
+                /**
+                 * @param array<string, string> \$properties
+                 */
+                public function __construct(array \$properties)
+                {
+                    \$this->properties = \$properties;
+                }
+                /** @return array<string, string> */
+                public function properties(): array
+                {
+                    return \$this->properties;
+                }
+                public function jsonSerialize(): mixed
+                {
+                    return ['properties' => \$this->properties];
+                }
+            }
+
+            PHP;
+
+        self::assertEquals($expected, $files['/generated/Metadata.php']);
+    }
+
+    #[Test]
+    public function record_with_enum_field(): void
+    {
+        $schema = <<<JSON
+            {
+                "type": "record",
+                "name": "Car",
+                "fields": [
+                    {"name": "brand", "type": "string"},
+                    {
+                        "name": "fuel",
+                        "type": {
+                            "type": "enum",
+                            "name": "FuelType",
+                            "symbols": ["gasoline", "diesel", "electric"]
+                        }
+                    }
+                ]
+            }
+            JSON;
+
+        $avroSchema = AvroSchema::parse($schema);
+        $files = $this->transpiler->translate($avroSchema, '/generated', 'App\\Vehicles');
+
+        self::assertCount(2, $files);
+        self::assertArrayHasKey('/generated/Car.php', $files);
+        self::assertArrayHasKey('/generated/FuelType.php', $files);
+
+        $expectedCar = <<<PHP
+            <?php
+            
+            declare(strict_types=1);
+            
+            namespace App\Vehicles;
+            
+            final class Car implements \JsonSerializable
+            {
+                private string \$brand;
+                private \App\Vehicles\FuelType \$fuel;
+                public function __construct(string \$brand, \App\Vehicles\FuelType \$fuel)
+                {
+                    \$this->brand = \$brand;
+                    \$this->fuel = \$fuel;
+                }
+                public function brand(): string
+                {
+                    return \$this->brand;
+                }
+                public function fuel(): \App\Vehicles\FuelType
+                {
+                    return \$this->fuel;
+                }
+                public function jsonSerialize(): mixed
+                {
+                    return ['brand' => \$this->brand, 'fuel' => \$this->fuel->value];
+                }
+            }
+
+            PHP;
+
+        self::assertEquals($expectedCar, $files['/generated/Car.php']);
+
+        $expectedEnum = <<<PHP
+            <?php
+            
+            declare(strict_types=1);
+            
+            namespace App\Vehicles;
+            
+            enum FuelType : string
+            {
+                case GASOLINE = 'gasoline';
+                case DIESEL = 'diesel';
+                case ELECTRIC = 'electric';
+            }
+
+            PHP;
+
+        self::assertEquals($expectedEnum, $files['/generated/FuelType.php']);
+    }
+
+    #[Test]
+    public function record_with_nullable_field(): void
+    {
+        $schema = <<<JSON
+            {
+                "type": "record",
+                "name": "Profile",
+                "fields": [
+                    {"name": "username", "type": "string"},
+                    {"name": "bio", "type": ["null", "string"], "default": null}
+                ]
+            }
+            JSON;
+
+        $avroSchema = AvroSchema::parse($schema);
+        $files = $this->transpiler->translate($avroSchema, '/generated', 'App\\Social');
+
+        self::assertCount(1, $files);
+        self::assertArrayHasKey('/generated/Profile.php', $files);
+
+        $expected = <<<PHP
+            <?php
+            
+            declare(strict_types=1);
+            
+            namespace App\Social;
+            
+            final class Profile implements \JsonSerializable
+            {
+                private string \$username;
+                private null|string \$bio = null;
+                public function __construct(string \$username, null|string \$bio = null)
+                {
+                    \$this->username = \$username;
+                    \$this->bio = \$bio;
+                }
+                public function username(): string
+                {
+                    return \$this->username;
+                }
+                public function bio(): null|string
+                {
+                    return \$this->bio;
+                }
+                public function jsonSerialize(): mixed
+                {
+                    return ['username' => \$this->username, 'bio' => \$this->bio];
+                }
+            }
+
+            PHP;
+
+        self::assertEquals($expected, $files['/generated/Profile.php']);
+    }
+
+    #[Test]
+    public function record_with_all_primitive_types(): void
+    {
+        $schema = <<<JSON
+            {
+                "type": "record",
+                "name": "AllTypes",
+                "fields": [
+                    {"name": "nullField", "type": "null"},
+                    {"name": "boolField", "type": "boolean"},
+                    {"name": "intField", "type": "int"},
+                    {"name": "longField", "type": "long"},
+                    {"name": "floatField", "type": "float"},
+                    {"name": "doubleField", "type": "double"},
+                    {"name": "stringField", "type": "string"},
+                    {"name": "bytesField", "type": "bytes"}
+                ]
+            }
+            JSON;
+
+        $avroSchema = AvroSchema::parse($schema);
+        $files = $this->transpiler->translate($avroSchema, '/generated', 'App\\Types');
+
+        self::assertCount(1, $files);
+        self::assertArrayHasKey('/generated/AllTypes.php', $files);
+
+        $expected = <<<PHP
+            <?php
+            
+            declare(strict_types=1);
+            
+            namespace App\Types;
+            
+            final class AllTypes implements \JsonSerializable
+            {
+                private null \$nullField;
+                private bool \$boolField;
+                private int \$intField;
+                private int \$longField;
+                private float \$floatField;
+                private float \$doubleField;
+                private string \$stringField;
+                private string \$bytesField;
+                public function __construct(null \$nullField, bool \$boolField, int \$intField, int \$longField, float \$floatField, float \$doubleField, string \$stringField, string \$bytesField)
+                {
+                    \$this->nullField = \$nullField;
+                    \$this->boolField = \$boolField;
+                    \$this->intField = \$intField;
+                    \$this->longField = \$longField;
+                    \$this->floatField = \$floatField;
+                    \$this->doubleField = \$doubleField;
+                    \$this->stringField = \$stringField;
+                    \$this->bytesField = \$bytesField;
+                }
+                public function nullField(): null
+                {
+                    return \$this->nullField;
+                }
+                public function boolField(): bool
+                {
+                    return \$this->boolField;
+                }
+                public function intField(): int
+                {
+                    return \$this->intField;
+                }
+                public function longField(): int
+                {
+                    return \$this->longField;
+                }
+                public function floatField(): float
+                {
+                    return \$this->floatField;
+                }
+                public function doubleField(): float
+                {
+                    return \$this->doubleField;
+                }
+                public function stringField(): string
+                {
+                    return \$this->stringField;
+                }
+                public function bytesField(): string
+                {
+                    return \$this->bytesField;
+                }
+                public function jsonSerialize(): mixed
+                {
+                    return ['nullField' => \$this->nullField, 'boolField' => \$this->boolField, 'intField' => \$this->intField, 'longField' => \$this->longField, 'floatField' => \$this->floatField, 'doubleField' => \$this->doubleField, 'stringField' => \$this->stringField, 'bytesField' => \$this->bytesField];
+                }
+            }
+
+            PHP;
+
+        self::assertEquals($expected, $files['/generated/AllTypes.php']);
+    }
+
+    #[Test]
+    public function record_with_nested_array_of_records(): void
+    {
+        $schema = <<<JSON
+            {
+                "type": "record",
+                "name": "Team",
+                "fields": [
+                    {"name": "name", "type": "string"},
+                    {
+                        "name": "members",
+                        "type": {
+                            "type": "array",
+                            "items": {
+                                "type": "record",
+                                "name": "Member",
+                                "fields": [
+                                    {"name": "name", "type": "string"},
+                                    {"name": "role", "type": "string"}
+                                ]
+                            }
+                        }
+                    }
+                ]
+            }
+            JSON;
+
+        $avroSchema = AvroSchema::parse($schema);
+        $files = $this->transpiler->translate($avroSchema, '/generated', 'App\\Org');
+
+        self::assertCount(2, $files);
+        self::assertArrayHasKey('/generated/Team.php', $files);
+        self::assertArrayHasKey('/generated/Member.php', $files);
+
+        $expectedTeam = <<<PHP
+            <?php
+            
+            declare(strict_types=1);
+            
+            namespace App\Org;
+            
+            final class Team implements \JsonSerializable
+            {
+                private string \$name;
+                /** @var list<\App\Org\Member> */
+                private array \$members;
+                /**
+                 * @param list<\App\Org\Member> \$members
+                 */
+                public function __construct(string \$name, array \$members)
+                {
+                    \$this->name = \$name;
+                    \$this->members = \$members;
+                }
+                public function name(): string
+                {
+                    return \$this->name;
+                }
+                /** @return list<\App\Org\Member> */
+                public function members(): array
+                {
+                    return \$this->members;
+                }
+                public function jsonSerialize(): mixed
+                {
+                    return ['name' => \$this->name, 'members' => \$this->members];
+                }
+            }
+
+            PHP;
+
+        self::assertEquals($expectedTeam, $files['/generated/Team.php']);
+
+        $expectedMember = <<<PHP
+            <?php
+            
+            declare(strict_types=1);
+            
+            namespace App\Org;
+            
+            final class Member implements \JsonSerializable
+            {
+                private string \$name;
+                private string \$role;
+                public function __construct(string \$name, string \$role)
+                {
+                    \$this->name = \$name;
+                    \$this->role = \$role;
+                }
+                public function name(): string
+                {
+                    return \$this->name;
+                }
+                public function role(): string
+                {
+                    return \$this->role;
+                }
+                public function jsonSerialize(): mixed
+                {
+                    return ['name' => \$this->name, 'role' => \$this->role];
+                }
+            }
+
+            PHP;
+
+        self::assertEquals($expectedMember, $files['/generated/Member.php']);
+    }
+
+    #[Test]
+    public function record_with_multiple_union_types(): void
+    {
+        $schema = <<<JSON
+            {
+                "type": "record",
+                "name": "Event",
+                "fields": [
+                    {"name": "payload", "type": ["null", "string", "int", "boolean"]}
+                ]
+            }
+            JSON;
+
+        $avroSchema = AvroSchema::parse($schema);
+        $files = $this->transpiler->translate($avroSchema, '/generated', 'App\\Events');
+
+        self::assertCount(1, $files);
+        self::assertArrayHasKey('/generated/Event.php', $files);
+
+        $expected = <<<PHP
+            <?php
+            
+            declare(strict_types=1);
+            
+            namespace App\Events;
+            
+            final class Event implements \JsonSerializable
+            {
+                private null|string|int|bool \$payload;
+                public function __construct(null|string|int|bool \$payload)
+                {
+                    \$this->payload = \$payload;
+                }
+                public function payload(): null|string|int|bool
+                {
+                    return \$this->payload;
+                }
+                public function jsonSerialize(): mixed
+                {
+                    return ['payload' => \$this->payload];
+                }
+            }
+
+            PHP;
+
+        self::assertEquals($expected, $files['/generated/Event.php']);
+    }
+
+    #[Test]
+    public function record_with_nested_record_field(): void
+    {
+        $schema = <<<JSON
+            {
+                "type": "record",
+                "name": "Order",
+                "fields": [
+                    {"name": "id", "type": "int"},
+                    {
+                        "name": "address",
+                        "type": {
+                            "type": "record",
+                            "name": "Address",
+                            "fields": [
+                                {"name": "street", "type": "string"},
+                                {"name": "city", "type": "string"}
+                            ]
+                        }
+                    }
+                ]
+            }
+            JSON;
+
+        $avroSchema = AvroSchema::parse($schema);
+        $files = $this->transpiler->translate($avroSchema, '/generated', 'App\\Shop');
+
+        self::assertCount(2, $files);
+        self::assertArrayHasKey('/generated/Order.php', $files);
+        self::assertArrayHasKey('/generated/Address.php', $files);
+
+        $expectedOrder = <<<PHP
+            <?php
+            
+            declare(strict_types=1);
+            
+            namespace App\Shop;
+            
+            final class Order implements \JsonSerializable
+            {
+                private int \$id;
+                private \App\Shop\Address \$address;
+                public function __construct(int \$id, \App\Shop\Address \$address)
+                {
+                    \$this->id = \$id;
+                    \$this->address = \$address;
+                }
+                public function id(): int
+                {
+                    return \$this->id;
+                }
+                public function address(): \App\Shop\Address
+                {
+                    return \$this->address;
+                }
+                public function jsonSerialize(): mixed
+                {
+                    return ['id' => \$this->id, 'address' => \$this->address];
+                }
+            }
+
+            PHP;
+
+        self::assertEquals($expectedOrder, $files['/generated/Order.php']);
+
+        $expectedAddress = <<<PHP
+            <?php
+            
+            declare(strict_types=1);
+            
+            namespace App\Shop;
+            
+            final class Address implements \JsonSerializable
+            {
+                private string \$street;
+                private string \$city;
+                public function __construct(string \$street, string \$city)
+                {
+                    \$this->street = \$street;
+                    \$this->city = \$city;
+                }
+                public function street(): string
+                {
+                    return \$this->street;
+                }
+                public function city(): string
+                {
+                    return \$this->city;
+                }
+                public function jsonSerialize(): mixed
+                {
+                    return ['street' => \$this->street, 'city' => \$this->city];
+                }
+            }
+
+            PHP;
+
+        self::assertEquals($expectedAddress, $files['/generated/Address.php']);
+    }
+
+    #[Test]
+    public function enum_with_single_symbol(): void
+    {
+        $schema = <<<JSON
+            {
+                "type": "enum",
+                "name": "Singleton",
+                "symbols": ["only"]
+            }
+            JSON;
+
+        $avroSchema = AvroSchema::parse($schema);
+        $files = $this->transpiler->translate($avroSchema, '/generated', 'App\\Enums');
+
+        self::assertCount(1, $files);
+        self::assertArrayHasKey('/generated/Singleton.php', $files);
+
+        $expected = <<<PHP
+            <?php
+            
+            declare(strict_types=1);
+            
+            namespace App\Enums;
+            
+            enum Singleton : string
+            {
+                case ONLY = 'only';
+            }
+
+            PHP;
+
+        self::assertEquals($expected, $files['/generated/Singleton.php']);
+    }
+
+    #[Test]
+    public function record_with_nullable_record_field(): void
+    {
+        $schema = <<<JSON
+            {
+                "type": "record",
+                "name": "Employee",
+                "fields": [
+                    {"name": "name", "type": "string"},
+                    {
+                        "name": "manager",
+                        "type": [
+                            "null",
+                            {
+                                "type": "record",
+                                "name": "Manager",
+                                "fields": [
+                                    {"name": "name", "type": "string"},
+                                    {"name": "department", "type": "string"}
+                                ]
+                            }
+                        ],
+                        "default": null
+                    }
+                ]
+            }
+            JSON;
+
+        $avroSchema = AvroSchema::parse($schema);
+        $files = $this->transpiler->translate($avroSchema, '/generated', 'App\\HR');
+
+        self::assertCount(2, $files);
+        self::assertArrayHasKey('/generated/Employee.php', $files);
+        self::assertArrayHasKey('/generated/Manager.php', $files);
+
+        $expectedEmployee = <<<PHP
+            <?php
+            
+            declare(strict_types=1);
+            
+            namespace App\HR;
+            
+            final class Employee implements \JsonSerializable
+            {
+                private string \$name;
+                private null|\App\HR\Manager \$manager = null;
+                public function __construct(string \$name, null|\App\HR\Manager \$manager = null)
+                {
+                    \$this->name = \$name;
+                    \$this->manager = \$manager;
+                }
+                public function name(): string
+                {
+                    return \$this->name;
+                }
+                public function manager(): null|\App\HR\Manager
+                {
+                    return \$this->manager;
+                }
+                public function jsonSerialize(): mixed
+                {
+                    return ['name' => \$this->name, 'manager' => \$this->manager];
+                }
+            }
+
+            PHP;
+
+        self::assertEquals($expectedEmployee, $files['/generated/Employee.php']);
+
+        $expectedManager = <<<PHP
+            <?php
+            
+            declare(strict_types=1);
+            
+            namespace App\HR;
+            
+            final class Manager implements \JsonSerializable
+            {
+                private string \$name;
+                private string \$department;
+                public function __construct(string \$name, string \$department)
+                {
+                    \$this->name = \$name;
+                    \$this->department = \$department;
+                }
+                public function name(): string
+                {
+                    return \$this->name;
+                }
+                public function department(): string
+                {
+                    return \$this->department;
+                }
+                public function jsonSerialize(): mixed
+                {
+                    return ['name' => \$this->name, 'department' => \$this->department];
+                }
+            }
+
+            PHP;
+
+        self::assertEquals($expectedManager, $files['/generated/Manager.php']);
+    }
+
+    #[Test]
+    public function record_with_map_of_records(): void
+    {
+        $schema = <<<JSON
+            {
+                "type": "record",
+                "name": "Library",
+                "fields": [
+                    {"name": "name", "type": "string"},
+                    {
+                        "name": "books",
+                        "type": {
+                            "type": "map",
+                            "values": {
+                                "type": "record",
+                                "name": "Book",
+                                "fields": [
+                                    {"name": "title", "type": "string"},
+                                    {"name": "pages", "type": "int"}
+                                ]
+                            }
+                        }
+                    }
+                ]
+            }
+            JSON;
+
+        $avroSchema = AvroSchema::parse($schema);
+        $files = $this->transpiler->translate($avroSchema, '/generated', 'App\\Library');
+
+        self::assertCount(2, $files);
+        self::assertArrayHasKey('/generated/Library.php', $files);
+        self::assertArrayHasKey('/generated/Book.php', $files);
+
+        $expectedLibrary = <<<PHP
+            <?php
+            
+            declare(strict_types=1);
+            
+            namespace App\Library;
+            
+            final class Library implements \JsonSerializable
+            {
+                private string \$name;
+                /** @var array<string, \App\Library\Book> */
+                private array \$books;
+                /**
+                 * @param array<string, \App\Library\Book> \$books
+                 */
+                public function __construct(string \$name, array \$books)
+                {
+                    \$this->name = \$name;
+                    \$this->books = \$books;
+                }
+                public function name(): string
+                {
+                    return \$this->name;
+                }
+                /** @return array<string, \App\Library\Book> */
+                public function books(): array
+                {
+                    return \$this->books;
+                }
+                public function jsonSerialize(): mixed
+                {
+                    return ['name' => \$this->name, 'books' => \$this->books];
+                }
+            }
+
+            PHP;
+
+        self::assertEquals($expectedLibrary, $files['/generated/Library.php']);
+
+        $expectedBook = <<<PHP
+            <?php
+            
+            declare(strict_types=1);
+            
+            namespace App\Library;
+            
+            final class Book implements \JsonSerializable
+            {
+                private string \$title;
+                private int \$pages;
+                public function __construct(string \$title, int \$pages)
+                {
+                    \$this->title = \$title;
+                    \$this->pages = \$pages;
+                }
+                public function title(): string
+                {
+                    return \$this->title;
+                }
+                public function pages(): int
+                {
+                    return \$this->pages;
+                }
+                public function jsonSerialize(): mixed
+                {
+                    return ['title' => \$this->title, 'pages' => \$this->pages];
+                }
+            }
+
+            PHP;
+
+        self::assertEquals($expectedBook, $files['/generated/Book.php']);
+    }
+
+    #[Test]
+    public function record_with_record_reuse_by_name(): void
+    {
+        $schema = <<<JSON
+            {
+                "type": "record",
+                "name": "Invoice",
+                "fields": [
+                    {"name": "id", "type": "int"},
+                    {
+                        "name": "billingAddress",
+                        "type": {
+                            "type": "record",
+                            "name": "PostalAddress",
+                            "fields": [
+                                {"name": "street", "type": "string"},
+                                {"name": "zip", "type": "string"}
+                            ]
+                        }
+                    },
+                    {
+                        "name": "shippingAddress",
+                        "type": "PostalAddress"
+                    }
+                ]
+            }
+            JSON;
+
+        $avroSchema = AvroSchema::parse($schema);
+        $files = $this->transpiler->translate($avroSchema, '/generated', 'App\\Billing');
+
+        self::assertCount(2, $files);
+        self::assertArrayHasKey('/generated/Invoice.php', $files);
+        self::assertArrayHasKey('/generated/PostalAddress.php', $files);
+
+        $expectedInvoice = <<<PHP
+            <?php
+            
+            declare(strict_types=1);
+            
+            namespace App\Billing;
+            
+            final class Invoice implements \JsonSerializable
+            {
+                private int \$id;
+                private \App\Billing\PostalAddress \$billingAddress;
+                private \App\Billing\PostalAddress \$shippingAddress;
+                public function __construct(int \$id, \App\Billing\PostalAddress \$billingAddress, \App\Billing\PostalAddress \$shippingAddress)
+                {
+                    \$this->id = \$id;
+                    \$this->billingAddress = \$billingAddress;
+                    \$this->shippingAddress = \$shippingAddress;
+                }
+                public function id(): int
+                {
+                    return \$this->id;
+                }
+                public function billingAddress(): \App\Billing\PostalAddress
+                {
+                    return \$this->billingAddress;
+                }
+                public function shippingAddress(): \App\Billing\PostalAddress
+                {
+                    return \$this->shippingAddress;
+                }
+                public function jsonSerialize(): mixed
+                {
+                    return ['id' => \$this->id, 'billingAddress' => \$this->billingAddress, 'shippingAddress' => \$this->shippingAddress];
+                }
+            }
+
+            PHP;
+
+        self::assertEquals($expectedInvoice, $files['/generated/Invoice.php']);
+    }
+
+    #[Test]
+    public function record_with_array_default_value(): void
+    {
+        $schema = <<<JSON
+            {
+                "type": "record",
+                "name": "Settings",
+                "fields": [
+                    {"name": "tags", "type": {"type": "array", "items": "string"}, "default": []}
+                ]
+            }
+            JSON;
+
+        $avroSchema = AvroSchema::parse($schema);
+        $files = $this->transpiler->translate($avroSchema, '/generated', 'App\\Config');
+
+        self::assertCount(1, $files);
+        self::assertArrayHasKey('/generated/Settings.php', $files);
+
+        $expected = <<<PHP
+            <?php
+            
+            declare(strict_types=1);
+            
+            namespace App\Config;
+            
+            final class Settings implements \JsonSerializable
+            {
+                /** @var list<string> */
+                private array \$tags = [];
+                /**
+                 * @param list<string> \$tags
+                 */
+                public function __construct(array \$tags = [])
+                {
+                    \$this->tags = \$tags;
+                }
+                /** @return list<string> */
+                public function tags(): array
+                {
+                    return \$this->tags;
+                }
+                public function jsonSerialize(): mixed
+                {
+                    return ['tags' => \$this->tags];
+                }
+            }
+
+            PHP;
+
+        self::assertEquals($expected, $files['/generated/Settings.php']);
+    }
+
+    #[Test]
+    public function record_with_mixed_default_and_required_fields(): void
+    {
+        $schema = <<<JSON
+            {
+                "type": "record",
+                "name": "Item",
+                "fields": [
+                    {"name": "name", "type": "string"},
+                    {"name": "quantity", "type": "int", "default": 1},
+                    {"name": "description", "type": "string", "default": "N/A"}
+                ]
+            }
+            JSON;
+
+        $avroSchema = AvroSchema::parse($schema);
+        $files = $this->transpiler->translate($avroSchema, '/generated', 'App\\Inventory');
+
+        self::assertCount(1, $files);
+        self::assertArrayHasKey('/generated/Item.php', $files);
+
+        $expected = <<<PHP
+            <?php
+            
+            declare(strict_types=1);
+            
+            namespace App\Inventory;
+            
+            final class Item implements \JsonSerializable
+            {
+                private string \$name;
+                private int \$quantity = 1;
+                private string \$description = 'N/A';
+                public function __construct(string \$name, int \$quantity = 1, string \$description = 'N/A')
+                {
+                    \$this->name = \$name;
+                    \$this->quantity = \$quantity;
+                    \$this->description = \$description;
+                }
+                public function name(): string
+                {
+                    return \$this->name;
+                }
+                public function quantity(): int
+                {
+                    return \$this->quantity;
+                }
+                public function description(): string
+                {
+                    return \$this->description;
+                }
+                public function jsonSerialize(): mixed
+                {
+                    return ['name' => \$this->name, 'quantity' => \$this->quantity, 'description' => \$this->description];
+                }
+            }
+
+            PHP;
+
+        self::assertEquals($expected, $files['/generated/Item.php']);
+    }
+
+    #[Test]
+    public function record_with_nullable_enum_field(): void
+    {
+        $schema = <<<JSON
+            {
+                "type": "record",
+                "name": "Task",
+                "fields": [
+                    {"name": "title", "type": "string"},
+                    {
+                        "name": "priority",
+                        "type": [
+                            "null",
+                            {
+                                "type": "enum",
+                                "name": "Priority",
+                                "symbols": ["low", "medium", "high"]
+                            }
+                        ],
+                        "default": null
+                    }
+                ]
+            }
+            JSON;
+
+        $avroSchema = AvroSchema::parse($schema);
+        $files = $this->transpiler->translate($avroSchema, '/generated', 'App\\Tasks');
+
+        self::assertCount(2, $files);
+        self::assertArrayHasKey('/generated/Task.php', $files);
+        self::assertArrayHasKey('/generated/Priority.php', $files);
+
+        $expectedTask = <<<PHP
+            <?php
+            
+            declare(strict_types=1);
+            
+            namespace App\Tasks;
+            
+            final class Task implements \JsonSerializable
+            {
+                private string \$title;
+                private null|\App\Tasks\Priority \$priority = null;
+                public function __construct(string \$title, null|\App\Tasks\Priority \$priority = null)
+                {
+                    \$this->title = \$title;
+                    \$this->priority = \$priority;
+                }
+                public function title(): string
+                {
+                    return \$this->title;
+                }
+                public function priority(): null|\App\Tasks\Priority
+                {
+                    return \$this->priority;
+                }
+                public function jsonSerialize(): mixed
+                {
+                    return ['title' => \$this->title, 'priority' => \$this->priority?->value];
+                }
+            }
+
+            PHP;
+
+        self::assertEquals($expectedTask, $files['/generated/Task.php']);
+
+        $expectedPriority = <<<PHP
+            <?php
+            
+            declare(strict_types=1);
+            
+            namespace App\Tasks;
+            
+            enum Priority : string
+            {
+                case LOW = 'low';
+                case MEDIUM = 'medium';
+                case HIGH = 'high';
+            }
+
+            PHP;
+
+        self::assertEquals($expectedPriority, $files['/generated/Priority.php']);
+    }
+
+    #[Test]
+    public function record_with_nullable_array_field(): void
+    {
+        $schema = <<<JSON
+            {
+                "type": "record",
+                "name": "Report",
+                "fields": [
+                    {"name": "title", "type": "string"},
+                    {
+                        "name": "scores",
+                        "type": ["null", {"type": "array", "items": "int"}],
+                        "default": null
+                    }
+                ]
+            }
+            JSON;
+
+        $avroSchema = AvroSchema::parse($schema);
+        $files = $this->transpiler->translate($avroSchema, '/generated', 'App\\Reports');
+
+        self::assertCount(1, $files);
+        self::assertArrayHasKey('/generated/Report.php', $files);
+
+        $expected = <<<PHP
+            <?php
+            
+            declare(strict_types=1);
+            
+            namespace App\Reports;
+            
+            final class Report implements \JsonSerializable
+            {
+                private string \$title;
+                /** @var null|list<int> */
+                private null|array \$scores = null;
+                /**
+                 * @param null|list<int> \$scores
+                 */
+                public function __construct(string \$title, null|array \$scores = null)
+                {
+                    \$this->title = \$title;
+                    \$this->scores = \$scores;
+                }
+                public function title(): string
+                {
+                    return \$this->title;
+                }
+                /** @return null|list<int> */
+                public function scores(): null|array
+                {
+                    return \$this->scores;
+                }
+                public function jsonSerialize(): mixed
+                {
+                    return ['title' => \$this->title, 'scores' => \$this->scores];
+                }
+            }
+
+            PHP;
+
+        self::assertEquals($expected, $files['/generated/Report.php']);
+    }
+
+    #[Test]
+    public function record_with_nullable_map_field(): void
+    {
+        $schema = <<<JSON
+            {
+                "type": "record",
+                "name": "Dashboard",
+                "fields": [
+                    {
+                        "name": "widgets",
+                        "type": ["null", {"type": "map", "values": "string"}],
+                        "default": null
+                    }
+                ]
+            }
+            JSON;
+
+        $avroSchema = AvroSchema::parse($schema);
+        $files = $this->transpiler->translate($avroSchema, '/generated', 'App\\UI');
+
+        self::assertCount(1, $files);
+        self::assertArrayHasKey('/generated/Dashboard.php', $files);
+
+        $expected = <<<PHP
+            <?php
+            
+            declare(strict_types=1);
+            
+            namespace App\UI;
+            
+            final class Dashboard implements \JsonSerializable
+            {
+                /** @var null|array<string, string> */
+                private null|array \$widgets = null;
+                /**
+                 * @param null|array<string, string> \$widgets
+                 */
+                public function __construct(null|array \$widgets = null)
+                {
+                    \$this->widgets = \$widgets;
+                }
+                /** @return null|array<string, string> */
+                public function widgets(): null|array
+                {
+                    return \$this->widgets;
+                }
+                public function jsonSerialize(): mixed
+                {
+                    return ['widgets' => \$this->widgets];
+                }
+            }
+
+            PHP;
+
+        self::assertEquals($expected, $files['/generated/Dashboard.php']);
+    }
+
+    #[Test]
+    public function record_with_nested_array_of_arrays(): void
+    {
+        $schema = <<<JSON
+            {
+                "type": "record",
+                "name": "Matrix",
+                "fields": [
+                    {
+                        "name": "rows",
+                        "type": {
+                            "type": "array",
+                            "items": {
+                                "type": "array",
+                                "items": "int"
+                            }
+                        }
+                    }
+                ]
+            }
+            JSON;
+
+        $avroSchema = AvroSchema::parse($schema);
+        $files = $this->transpiler->translate($avroSchema, '/generated', 'App\\Math');
+
+        self::assertCount(1, $files);
+        self::assertArrayHasKey('/generated/Matrix.php', $files);
+
+        $expected = <<<PHP
+            <?php
+            
+            declare(strict_types=1);
+            
+            namespace App\Math;
+            
+            final class Matrix implements \JsonSerializable
+            {
+                /** @var list<list<int>> */
+                private array \$rows;
+                /**
+                 * @param list<list<int>> \$rows
+                 */
+                public function __construct(array \$rows)
+                {
+                    \$this->rows = \$rows;
+                }
+                /** @return list<list<int>> */
+                public function rows(): array
+                {
+                    return \$this->rows;
+                }
+                public function jsonSerialize(): mixed
+                {
+                    return ['rows' => \$this->rows];
+                }
+            }
+
+            PHP;
+
+        self::assertEquals($expected, $files['/generated/Matrix.php']);
+    }
+
+    #[Test]
+    public function record_with_map_of_arrays(): void
+    {
+        $schema = <<<JSON
+            {
+                "type": "record",
+                "name": "Index",
+                "fields": [
+                    {
+                        "name": "entries",
+                        "type": {
+                            "type": "map",
+                            "values": {
+                                "type": "array",
+                                "items": "string"
+                            }
+                        }
+                    }
+                ]
+            }
+            JSON;
+
+        $avroSchema = AvroSchema::parse($schema);
+        $files = $this->transpiler->translate($avroSchema, '/generated', 'App\\Search');
+
+        self::assertCount(1, $files);
+        self::assertArrayHasKey('/generated/Index.php', $files);
+
+        $expected = <<<PHP
+            <?php
+            
+            declare(strict_types=1);
+            
+            namespace App\Search;
+            
+            final class Index implements \JsonSerializable
+            {
+                /** @var array<string, list<string>> */
+                private array \$entries;
+                /**
+                 * @param array<string, list<string>> \$entries
+                 */
+                public function __construct(array \$entries)
+                {
+                    \$this->entries = \$entries;
+                }
+                /** @return array<string, list<string>> */
+                public function entries(): array
+                {
+                    return \$this->entries;
+                }
+                public function jsonSerialize(): mixed
+                {
+                    return ['entries' => \$this->entries];
+                }
+            }
+
+            PHP;
+
+        self::assertEquals($expected, $files['/generated/Index.php']);
+    }
+}