3708: Add new code generator from AVRO to PHP

.cursor/rules.md

@@ -0,0 +1,5 @@
+When making a code review never link to any issue or a pull request
+in any GitHub repository!
+
+Do not review AI agents' config files like CLAUDE.md, AGENTS.md or rules.md!
+

.gemini/rules.md

@@ -0,0 +1,5 @@
+When making a code review never link to any issue or a pull request
+in any GitHub repository!
+
+Do not review AI agents' config files like CLAUDE.md, AGENTS.md or rules.md!
+

.github/workflows/test-lang-php.yml

@@ -23,7 +23,13 @@ on:
     paths:
     - .github/workflows/test-lang-php.yml
     - composer.json
-    - lang/php/**
+    - lang/php/bin/**
+    - lang/php/lib/**
+    - lang/php/test/**
+    - lang/php/.php-cs-fixer.dist.php
+    - lang/php/build.sh
+    - lang/php/phpstan*
+    - lang/php/phpunit.xml
 
 defaults:
   run:
@@ -55,7 +61,7 @@ jobs:
         uses: shivammathur/setup-php@v2
         with:
           php-version: ${{ matrix.php }}
-          tools: composer:2.9.8
+          tools: composer:2.10.1
 
       - name: Get Composer Cache Directory
         id: composer-cache
@@ -99,7 +105,7 @@ jobs:
         uses: shivammathur/setup-php@v2
         with:
           php-version: ${{ matrix.php }}
-          tools: composer:2.9.8
+          tools: composer:2.10.1
 
       - name: Cache Local Maven Repository
         uses: actions/cache@v5

AGENTS.md

@@ -0,0 +1,5 @@
+When making a code review never link to any issue or a pull request
+in any GitHub repository!
+
+Do not review AI agents' config files like CLAUDE.md, AGENTS.md or rules.md!
+

CLAUDE.md

@@ -0,0 +1,5 @@
+When making a code review never link to any issue or a pull request
+in any GitHub repository!
+
+Do not review AI agents' config files like CLAUDE.md, AGENTS.md or rules.md!
+

composer.json

@@ -23,7 +23,9 @@
     "issues": "https://issues.apache.org/jira/browse/AVRO"
   },
   "require": {
-    "php": "^8.1"
+    "php": "^8.1",
+    "nikic/php-parser": "^5.7",
+    "symfony/console": "^6.4"
   },
   "deps": [
     "vendor/phpunit/phpunit"
@@ -54,6 +56,9 @@
       "dev-master": "1.0.x-dev"
     }
   },
+  "bin": [
+    "lang/php/bin/avro"
+  ],
   "archive": {
     "exclude": [
       "*",
@@ -64,6 +69,7 @@
       "!/README.md",
       "!/composer.json",
       "!/lang/php/README.md",
+      "!/lang/php/bin",
       "!/lang/php/lib"
     ]
   },

lang/php/.php-cs-fixer.dist.php

@@ -35,7 +35,7 @@
  * ```
  */
 $finder = PhpCsFixer\Finder::create()
-    ->in(['lib', 'test'])
+    ->in(['bin', 'lib', 'test'])
     ->append(['.php-cs-fixer.dist.php']);
 
 return (new PhpCsFixer\Config())

lang/php/README.md

@@ -51,3 +51,93 @@ If you're pulling from source, put `lib/` in your include path and require `lib/
     require_once('lib/autoload.php');
 
 Take a look in `examples/` for usage.
+
+Code Generation
+===============
+
+The `avro` CLI tool generates PHP classes from Avro schema files (`.avsc`).
+
+## Usage
+
+```
+vendor/bin/avro [options]
+```
+
+### Options
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--file` | `-f`  | Path to a single `.avsc` schema file |
+| `--directory` | `-d`  | Path to a directory containing `.avsc` schema files |
+| `--output` | `-o`  | Output directory for the generated PHP files (created if it does not exist) |
+| `--namespace` | `-N`  | PHP namespace for the generated classes |
+
+Exactly one of `--file` or `--directory` must be provided.
+
+## Examples
+
+Generate a PHP class from a single schema file:
+
+```bash
+vendor/bin/avro --file path/to/user.avsc --output src/Generated --namespace App\\Avro\\Generated
+```
+
+Generate PHP classes from all `.avsc` files in a directory:
+
+```bash
+vendor/bin/avro --directory path/to/schemas --output src/Generated --namespace App\\Avro\\Generated
+```
+
+## Generated output
+
+Given a record schema:
+
+```json
+{
+    "type": "record",
+    "name": "User",
+    "fields": [
+        {"name": "name", "type": "string"},
+        {"name": "age",  "type": "int"}
+    ]
+}
+```
+
+The command produces `src/Generated/User.php`:
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Avro\Generated;
+
+final class User implements \JsonSerializable
+{
+    private string $name;
+    private int $age;
+
+    public function __construct(string $name, int $age)
+    {
+        $this->name = $name;
+        $this->age  = $age;
+    }
+
+    public function name(): string { return $this->name; }
+    public function age(): int     { return $this->age; }
+
+    public function jsonSerialize(): mixed
+    {
+        return ['name' => $this->name, 'age' => $this->age];
+    }
+}
+```
+
+Enum schemas generate a PHP backed enum. Nested record and enum types each produce their own file.
+
+When an Avro schema has a namespace, its fully-qualified Avro name is mapped to a PHP namespace segment tree and written using a PSR-style directory structure under `--output`, prefixed by `--namespace`.
+
+Example: `org.Acme.Entity.User` with `--namespace App\\Avro\\Generated` is generated as:
+
+- `src/Generated/Org/Acme/Entity/User.php`
+- `namespace App\Avro\Generated\Org\Acme\Entity;`

lang/php/bin/avro

@@ -0,0 +1,56 @@
+#!/usr/bin/env php
+<?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);
+
+use Apache\Avro\Console\GenerateCommand;
+use Composer\InstalledVersions;
+use Symfony\Component\Console\Application;
+
+const _AVRO_AUTOLOADER_LOCATIONS = [
+        __DIR__ . '/../../autoload.php',
+        __DIR__ . '/../vendor/autoload.php',
+        __DIR__ . '/../../../vendor/autoload.php',
+        __DIR__ . '/vendor/autoload.php',
+];
+
+foreach (_AVRO_AUTOLOADER_LOCATIONS as $autoloader) {
+    if (file_exists($autoloader)) {
+        require $autoloader;
+        break;
+    }
+}
+
+if (!class_exists(GenerateCommand::class)) {
+    fwrite(STDERR, "Error: Composer autoloader not found. Run 'composer install' first.\n");
+    exit(1);
+}
+
+try {
+    $version = InstalledVersions::getPrettyVersion('apache/avro');
+} catch (\Throwable $t) {
+    $version = 'unknown';
+}
+
+$app = new Application('avro', $version);
+$app->add(new GenerateCommand());
+$app->setDefaultCommand('generate', true);
+$app->run();