Add new code generator from AVRO to PHP

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"

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);
+    }
+}