Add new code generator from AVRO to PHP by mattiabasone · Pull Request #3708 · apache/avro

mattiabasone · 2026-03-27T15:31:22Z

What is the purpose of the change

Adds an Avro to PHP code generator and AvroSpecificDatumWriter to serialise autogenerated classes in Avro

Verifying this change

New feature with new tests

Documentation

Does this pull request introduce a new feature? yes
If yes, how is the feature documented? Added a new section in the README.md file

…erator

…o add-schema-to-php-generator

Copilot

Pull request overview

This PR adds a PHP code-generation pipeline to the Avro PHP implementation, including a new avro CLI command, a schema-to-PHP code generator, and a “specific” datum writer for serializing generated classes.

Changes:

Add AvroCodeGenerator (schema → PHP records/enums) and GenerateCommand + lang/php/bin/avro CLI entrypoint.
Add AvroSpecificDatumWriter to serialize generated record objects/enums to Avro binary.
Add PHPUnit coverage and fixtures; update PHP tooling config (PHPStan/CS Fixer) and CI paths; add new Composer dependencies.

Reviewed changes

Copilot reviewed 18 out of 30 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
lang/php/test/Generator/AvroCodeGeneratorTest.php	Adds extensive unit tests asserting generated PHP output for many schema shapes
lang/php/test/Fixtures/Schemas/user.avsc	Fixture schema for CLI generation tests (record)
lang/php/test/Fixtures/Schemas/status.avsc	Fixture schema for CLI generation tests (enum)
lang/php/test/Fixtures/Generated/User.php	Generated-class fixture used by specific writer tests
lang/php/test/Fixtures/Generated/Team.php	Generated-class fixture used by specific writer tests
lang/php/test/Fixtures/Generated/Task.php	Generated-class fixture used by specific writer tests
lang/php/test/Fixtures/Generated/Profile.php	Generated-class fixture used by specific writer tests
lang/php/test/Fixtures/Generated/Priority.php	Generated-enum fixture used by specific writer tests
lang/php/test/Fixtures/Generated/Order.php	Generated-class fixture used by specific writer tests
lang/php/test/Fixtures/Generated/Metadata.php	Generated-class fixture used by specific writer tests
lang/php/test/Fixtures/Generated/Member.php	Generated-class fixture used by specific writer tests
lang/php/test/Fixtures/Generated/FuelType.php	Generated-enum fixture used by specific writer tests
lang/php/test/Fixtures/Generated/Car.php	Generated-class fixture used by specific writer tests
lang/php/test/Fixtures/Generated/Address.php	Generated-class fixture used by specific writer tests
lang/php/test/Datum/AvroSpecificDatumWriterTest.php	Adds round-trip and byte-equivalence tests for the new specific writer
lang/php/test/Console/GenerateCommandTest.php	Adds Symfony Console command tests for the generator CLI
lang/php/README.md	Documents the new code generation CLI usage and output
lang/php/phpstan.neon	Includes `bin/` in PHPStan scan paths
lang/php/lib/Schema/AvroSchema.php	Fixes JSON decoding usage and wraps JSON parse errors in `AvroSchemaParseException`
lang/php/lib/Schema/AvroNamedSchema.php	Exposes short `name()` accessor for named schemas
lang/php/lib/Schema/AvroName.php	Exposes short `name()` accessor for schema names
lang/php/lib/Schema/AvroEnumSchema.php	Adds return types / minor signature tightening for enum helpers
lang/php/lib/Generator/AvroCodeGeneratorException.php	Adds generator-specific exception type
lang/php/lib/Generator/AvroCodeGenerator.php	Implements schema traversal + PHP AST generation via nikic/php-parser
lang/php/lib/Datum/AvroSpecificDatumWriter.php	Implements object-based datum writing according to schema
lang/php/lib/Console/GenerateCommand.php	Adds `generate` console command for file/directory schema inputs
lang/php/bin/avro	Adds a composer-bin CLI entrypoint for the generator
lang/php/.php-cs-fixer.dist.php	Includes `bin/` in code style fixer scope
composer.json	Adds `nikic/php-parser` + `symfony/console`, registers the `avro` binary, updates archive include list
.github/workflows/test-lang-php.yml	Narrows path filters to PHP-relevant paths and bumps Composer tool version

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

martin-g · 2026-06-22T15:32:32Z

+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+


Please add some documentation about the purpose of this file.

martin-g · 2026-06-23T07:01:09Z

+            };
+
+            if (null !== $node && $registeredSchema instanceof AvroNamedSchema) {
+                $filename = $path.'/'.ucwords($registeredSchema->name()).'.php';


This should probably use the schema fullname, i.e. namespace + name. Currently it will overwrite the file if there are two schemas with the same name in different namespaces.

What do you think about providing only a root namespace for the generated files (e.g. \MyExternalService), and the remaining part of the namespace is the one provided by the Avro schema (e.g. Something.Domain.BlaBla) and the namespace will be something like \MyExternalService\Something\Domain\BlaBla\?
The change will be reflected on the path on disk to be autoload-compliant

Sounds good to me!

martin-g · 2026-06-23T07:03:08Z

+        string $phpNamespace,
+        array $values
+    ): Node {
+        $className = ucwords($avroEnum->name());


Same issue here - should the fullname be used ?

martin-g · 2026-06-23T07:05:36Z

+        $enum = $this->factory->enum($className)->setScalarType('string');
+
+        foreach ($values as $value) {
+            $caseName = strtoupper($value);


Names in Avro are case-sensitive, i.e. schemas with names "name" and "Name" are OK to exist at the same time.
strtoupper() will lead to a collision in the PHP class name.

martin-g · 2026-06-23T07:08:02Z

+            }
+        }
+
+        if ([] !== $written) {


An empty directory (i.e. files == []) will be reported as success. Is this intentional ?
I am not sure how the other SDK generators behave.

martin-g · 2026-06-23T07:37:40Z

+use Composer\InstalledVersions;
+use Symfony\Component\Console\Application;
+
+$version = InstalledVersions::getPrettyVersion('apache/avro');


Suggested change

$version = InstalledVersions::getPrettyVersion('apache/avro');

try {

$version = InstalledVersions::getPrettyVersion('apache/avro') ?? 'unknown';

} catch (\Throwable) {

$version = 'unknown';

}

martin-g · 2026-06-23T07:47:30Z

+
+    private function collectSchemas(AvroSchema $schema): void
+    {
+        switch ($schema::class) {


Elsewhere you use match (true) { $schema instanceof Foo => ...}.
Why this is different ?

martin-g · 2026-06-23T07:49:25Z

+            ->addOption('file', 'f', InputOption::VALUE_OPTIONAL, 'One Avro schema file (.avsc)')
+            ->addOption('directory', 'd', InputOption::VALUE_OPTIONAL, 'A directory containing multiple Avro schema files (.avsc)')
+            ->addOption('output', 'o', InputOption::VALUE_REQUIRED, 'Output directory for generated PHP files')
+            ->addOption('namespace', 'ns', InputOption::VALUE_REQUIRED, 'PHP namespace for generated classes');


Suggested change

->addOption('namespace', 'ns', InputOption::VALUE_REQUIRED, 'PHP namespace for generated classes');

->addOption('namespace', 'n', InputOption::VALUE_REQUIRED, 'PHP namespace for generated classes');

Usually the short options are single character

The -n is already taken by the Symfony Console Component

-n, --no-interaction Do not ask any interactive question

We could use a capital N, wdyt?

martin-g · 2026-06-23T07:52:20Z

-    public function hasSymbol($symbol)
+    public function hasSymbol($symbol): bool
    {
        return in_array($symbol, $this->symbols);


Suggested change

return in_array($symbol, $this->symbols);

return is_string($symbol) && in_array($symbol, $this->symbols, true);

a bit more strict check

martin-g · 2026-06-23T07:54:10Z

+        $tester->execute([
+            '--file' => $this->schemaPath('user.avsc'),
+            '--output' => $this->outputDir,
+            '--namespace' => 'My\\App\\Avro',
+        ]);
+


Suggested change

$tester->execute([

'--file' => $this->schemaPath('user.avsc'),

'--output' => $this->outputDir,

'--namespace' => 'My\\App\\Avro',

]);

$exitCode = $tester->execute([

'--file' => $this->schemaPath('user.avsc'),

'--output' => $this->outputDir,

'--namespace' => 'My\\App\\Avro',

]);

self::assertSame(Command::SUCCESS, $exitCode);

self::assertFileExists($this->outputDir.'/User.php');

mattiabasone added 3 commits January 30, 2026 17:17

Add AvroTranspiler and test (wip)

e2b764c

add new functionalities to AvroTranspiler

84e7264

renaming

5ce7149

github-actions Bot added the PHP label Mar 27, 2026

mattiabasone changed the title ~~Add schema to php generator~~ Add new code generator from AVRO to PHP Mar 27, 2026

mattiabasone added 6 commits April 10, 2026 17:31

add AvroSpecificDatumWriter and tests + fixtures

8147d94

add new command, run cs-fix and fix newlines

cb41450

symfony/console 6.4

d5794a6

format

662f7d2

add new section in README.md

2366b1c

update paths

3ca4e2f

github-actions Bot added the build label May 15, 2026

mattiabasone added 6 commits June 12, 2026 15:21

bump composer version

54fde5a

Merge remote-tracking branch 'origin/main' into add-schema-to-php-gen…

53b5da7

…erator

Merge branch 'main' into add-schema-to-php-generator

456961b

fix

88fdcdc

Merge remote-tracking branch 'origin/add-schema-to-php-generator' int…

56ac403

…o add-schema-to-php-generator

properly handle exception

067dca1

mattiabasone marked this pull request as ready for review June 12, 2026 13:43

mattiabasone requested a review from Copilot June 12, 2026 13:43

Copilot started reviewing on behalf of mattiabasone June 12, 2026 13:44 View session

Copilot AI reviewed Jun 12, 2026

View reviewed changes

copilot review

cd9b00d

mattiabasone requested a review from martin-g June 12, 2026 14:18

martin-g reviewed Jun 23, 2026

View reviewed changes

-$version = InstalledVersions::getPrettyVersion('apache/avro');
+try {
+    $version = InstalledVersions::getPrettyVersion('apache/avro') ?? 'unknown';
+} catch (\Throwable) {
+    $version = 'unknown';
+}

	->addOption('namespace', 'ns', InputOption::VALUE_REQUIRED, 'PHP namespace for generated classes');
	->addOption('namespace', 'n', InputOption::VALUE_REQUIRED, 'PHP namespace for generated classes');

	return in_array($symbol, $this->symbols);
	return is_string($symbol) && in_array($symbol, $this->symbols, true);

Uh oh!

Conversation

mattiabasone commented Mar 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What is the purpose of the change

Verifying this change

Documentation

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mattiabasone Jun 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mattiabasone Jun 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mattiabasone commented Mar 27, 2026 •

edited

Loading

mattiabasone Jun 26, 2026 •

edited

Loading

mattiabasone Jun 26, 2026 •

edited

Loading