skir-php-generator 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maxim Kerstens
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,112 @@
+# Skir PHP Generator
+
+Generates framework-agnostic PHP data objects for Skir schemas.
+
+Generated PHP code uses `php-skir/runtime` for dense JSON serialization. If you use generated RPC clients, install `php-skir/client` as well.
+
+## Installation
+
+```bash
+npm install --save-dev skir-php-generator
+composer require php-skir/runtime
+```
+
+For generated typed RPC clients:
+
+```bash
+composer require php-skir/client
+```
+
+## Releasing
+
+Create a GitHub release for the version in `package.json`. The release workflow reruns type checks, build, package validation, and tests before publishing to npm with provenance. It expects an `NPM_TOKEN` repository secret.
+
+## Usage with Skir
+
+Add the generator to `skir.yml`:
+
+```yaml
+generators:
+  php:
+    package: skir-php-generator
+    output: generated/php
+    config:
+      namespace: App\Skir
+```
+
+Then run the Skir generator command for your project.
+
+## Generated PHP
+
+The generator emits readonly PHP classes for Skir structs and enum wrapper classes for Skir enums. Generated classes expose:
+
+- `skirType()` for runtime type descriptors.
+- `toArray()` and `fromArray()` for PHP array conversion.
+- `toDenseJson()` and `fromDenseJson()` for dense JSON payloads.
+- `toSkirValue()` and `fromSkirValue()` on generated enum classes.
+
+SkirRPC methods are emitted in `SkirMethods.php` as `MethodDescriptor` instances. The generator also emits a module-scoped method enum such as `AdminSkirMethod.php` for attribute-based server routing.
+
+When a module defines SkirRPC methods, the generator also emits `SkirRpcClient.php`. It wraps `Skir\Client\SkirClient` and exposes typed methods:
+
+```php
+use App\Skir\Admin\SkirRpcClient;
+use Skir\Client\SkirClient as TransportSkirClient;
+
+$client = new SkirRpcClient(new TransportSkirClient('https://example.com/skir'));
+$user = $client->getUser($request);
+```
+
+For servers, the generator emits `AdminSkirMethod.php`, `AbstractSkirProcedures.php`, `SkirProcedures.php`, and `SkirProcedureProvider.php`.
+
+The recommended Laravel server path is to use the generated method enum with `php-skir/server` controller routing:
+
+```php
+use App\Skir\Admin\AdminSkirMethod;
+use App\Skir\Admin\GetUserRequest;
+use App\Skir\Admin\User;
+use Skir\Server\Attributes\SkirMethod;
+use Skir\Server\SkirContext;
+
+final class UserController
+{
+    #[SkirMethod(AdminSkirMethod::GetUser)]
+    public function get(GetUserRequest $request, SkirContext $context): User
+    {
+        return new User(
+            userId: $request->userId,
+            name: 'Maxim',
+        );
+    }
+}
+```
+
+Register the controller on a Skir endpoint:
+
+```php
+use App\Skir\Controllers\UserController;
+use Illuminate\Support\Facades\Route;
+use Skir\Server\Facades\Skir;
+
+Route::skirRpc('/api/skir', [
+    Skir::controller(UserController::class),
+]);
+```
+
+The method enum resolves back to `SkirMethods::getUser()`, so the Skir schema remains the source of truth while your IDE can autocomplete enum cases.
+
+The abstract procedure and interface/provider pair remain available as lower-level compatibility APIs.
+
+## Namespaces and modules
+
+The configured namespace defaults to `App\Skir`. Module directories become PHP subnamespaces and output directories:
+
+```text
+admin/users.skir -> App\Skir\Admin
+```
+
+When two generated records would otherwise use the same PHP class name in the same namespace, the generator prefixes the class with the module basename to keep output deterministic.
+
+## Current scope
+
+This package generates framework-agnostic PHP DTOs, method descriptors, typed client adapters, and Laravel Skir server procedure adapters. Laravel-specific data objects and server routing live in separate packages.

package/dist/generator.d.ts

@@ -0,0 +1,65 @@
+export interface PhpGeneratorConfig {
+    readonly namespace?: string;
+}
+export interface PhpGeneratorInput {
+    readonly config?: PhpGeneratorConfig;
+    readonly modules: readonly SkirModule[];
+    readonly recordMap?: ReadonlyMap<string, SkirRecordLocation>;
+}
+export interface SkirModule {
+    readonly path: string;
+    readonly records?: readonly (SkirRecord | SkirRecordLocation)[];
+    readonly methods?: readonly SkirMethod[];
+}
+export interface SkirRecordLocation {
+    readonly kind: "record-location";
+    readonly record: SkirRecord;
+    readonly recordAncestors?: readonly SkirRecord[];
+    readonly modulePath?: string;
+}
+export interface SkirRecord {
+    readonly kind?: string;
+    readonly key?: unknown;
+    readonly name: string | SkirToken;
+    readonly recordType?: "struct" | "enum";
+    readonly fields?: readonly SkirField[];
+    readonly removedNumbers?: readonly number[];
+    readonly phpClassName?: string;
+}
+export type SkirField = {
+    readonly kind: "field";
+    readonly name: string | SkirToken;
+    readonly number: number;
+    readonly type?: SkirType;
+} | {
+    readonly kind: "removed";
+    readonly number: number;
+};
+export type SkirType = string | {
+    readonly kind: string;
+    readonly primitive?: string;
+    readonly item?: SkirType;
+    readonly other?: SkirType;
+    readonly key?: unknown;
+    readonly name?: string | SkirToken;
+    readonly nameParts?: readonly SkirRecordNamePart[];
+    readonly recordType?: "struct" | "enum";
+};
+export interface SkirToken {
+    readonly text: string;
+}
+export type SkirRecordNamePart = string | SkirToken | {
+    readonly token: string | SkirToken;
+};
+export interface SkirMethod {
+    readonly kind: "method";
+    readonly name: string | SkirToken;
+    readonly number: number;
+    readonly requestType?: SkirType;
+    readonly responseType?: SkirType;
+}
+export interface GeneratedFile {
+    readonly path: string;
+    readonly code: string;
+}
+export declare function generatePhpFiles(input: PhpGeneratorInput): GeneratedFile[];

package/dist/generator.js

@@ -0,0 +1,968 @@
+export function generatePhpFiles(input) {
+    const namespace = input.config?.namespace ?? "App\\Skir";
+    const classNames = buildClassNameRegistry(namespace, input.modules);
+    const methodGroups = new Map();
+    const recordFiles = [];
+    for (const module of input.modules) {
+        const context = outputContextForModule(namespace, module, input.recordMap, classNames);
+        recordFiles.push(...(module.records ?? [])
+            .map((record, index) => normalizeRecord(record, module, index, classNames))
+            .filter((record) => isStruct(record) || isEnum(record))
+            .map((record) => isEnum(record)
+            ? generateEnumFile(context, record)
+            : generateStructFile(context, record)));
+        const methods = module.methods ?? [];
+        if (methods.length > 0) {
+            const groupKey = `${context.namespace}\n${context.pathPrefix}`;
+            const existingGroup = methodGroups.get(groupKey);
+            if (existingGroup !== undefined) {
+                existingGroup.methods.push(...methods);
+            }
+            else {
+                methodGroups.set(groupKey, {
+                    context,
+                    methods: [...methods],
+                });
+            }
+        }
+    }
+    return [
+        ...recordFiles,
+        ...Array.from(methodGroups.values()).flatMap((group) => [
+            generateMethodsFile(group.context, group.methods),
+            generateMethodEnumFile(group.context, group.methods),
+            generateClientFile(group.context, group.methods),
+            generateProceduresFile(group.context, group.methods),
+            generateAbstractProceduresFile(group.context, group.methods),
+            generateProcedureProviderFile(group.context, group.methods),
+        ]),
+    ];
+}
+function generateStructFile(context, record) {
+    const className = classNameForRecord(record);
+    const fields = collectStructFields(record);
+    const runtimeImports = [
+        "Skir\\Runtime\\DenseJson",
+        "Skir\\Runtime\\Field",
+        "Skir\\Runtime\\Type",
+    ];
+    const fileContext = fileOutputContext(context, className, runtimeImports);
+    const constructor = generateConstructor(fields, fileContext);
+    const skirType = generateSkirType(record, fileContext);
+    const fromArray = generateFromArray(className, fields, fileContext);
+    const classMembers = [
+        constructor,
+        skirType,
+        generateToArray(fields, fileContext),
+        fromArray,
+        generateToDenseJson(),
+        generateFromDenseJson(className),
+    ].filter((member) => member !== null);
+    return {
+        path: outputPath(context, `${className}.php`),
+        code: [
+            "<?php",
+            "",
+            "declare(strict_types=1);",
+            "",
+            `namespace ${context.namespace};`,
+            "",
+            ...generateUseStatements(fileContext, runtimeImports),
+            "",
+            `final readonly class ${className}`,
+            "{",
+            ...classMembers.flatMap((member, index) => index === 0
+                ? [indent(member)]
+                : ["", indent(member)]),
+            "}",
+            "",
+        ].join("\n"),
+    };
+}
+function generateConstructor(fields, context) {
+    if (fields.length === 0) {
+        return null;
+    }
+    return [
+        "public function __construct(",
+        ...fields.map((field) => `    public ${phpType(field.type, context)} $${toPropertyName(field.name)},`),
+        ") {}",
+    ].join("\n");
+}
+function generateSkirType(record, context) {
+    const entries = collectDeclarations(record, "string")
+        .map((declaration) => {
+        if (isRemovedDeclaration(declaration)) {
+            return `    Field::removed(${declaration.number}),`;
+        }
+        return `    Field::value('${declaration.name}', ${declaration.number}, ${runtimeTypeExpression(declaration.type ?? "string", context)}),`;
+    })
+        .join("\n");
+    return [
+        "public static function skirType(): Type",
+        "{",
+        "    return Type::struct([",
+        entries,
+        "    ]);",
+        "}",
+    ].join("\n");
+}
+function generateToArray(fields, context) {
+    return [
+        "/** @return array<string, mixed> */",
+        "public function toArray(): array",
+        "{",
+        "    return [",
+        ...fields.map((field) => {
+            const property = toPropertyName(field.name);
+            return `        '${field.name}' => ${valueToArrayExpression(field.type, `$this->${property}`, context)},`;
+        }),
+        "    ];",
+        "}",
+    ].join("\n");
+}
+function generateFromArray(className, fields, context) {
+    return [
+        "/** @param array<string, mixed> $data */",
+        `public static function fromArray(array $data): ${className}`,
+        "{",
+        "    return new self(",
+        ...fields.map((field) => `        ${toPropertyName(field.name)}: ${valueFromArrayExpression(field.type, `$data['${field.name}']`, context)},`),
+        "    );",
+        "}",
+    ].join("\n");
+}
+function generateToDenseJson() {
+    return [
+        "public function toDenseJson(): string",
+        "{",
+        "    return DenseJson::toJson(self::skirType(), $this->toArray());",
+        "}",
+    ].join("\n");
+}
+function generateFromDenseJson(className) {
+    return [
+        `public static function fromDenseJson(string $json): ${className}`,
+        "{",
+        "    return self::fromArray(DenseJson::fromJson(self::skirType(), $json));",
+        "}",
+    ].join("\n");
+}
+function generateEnumFile(context, record) {
+    const className = classNameForRecord(record);
+    const variants = collectDeclarations(record);
+    const runtimeImports = [
+        "Skir\\Runtime\\DenseJson",
+        "Skir\\Runtime\\EnumValue",
+        "Skir\\Runtime\\Type",
+        "Skir\\Runtime\\Variant",
+    ];
+    const fileContext = fileOutputContext(context, className, runtimeImports);
+    const constructors = generateEnumConstructors(variants, fileContext);
+    const skirType = generateEnumSkirType(record, fileContext);
+    return {
+        path: outputPath(context, `${className}.php`),
+        code: [
+            "<?php",
+            "",
+            "declare(strict_types=1);",
+            "",
+            `namespace ${context.namespace};`,
+            "",
+            ...generateUseStatements(fileContext, runtimeImports),
+            "",
+            `final readonly class ${className}`,
+            "{",
+            indent("private function __construct(private EnumValue $value) {}"),
+            "",
+            indent(constructors),
+            "",
+            indent(skirType),
+            "",
+            indent(generateEnumAccessors()),
+            "",
+            indent(generateEnumToSkirValue()),
+            "",
+            indent(generateEnumFromSkirValue(className)),
+            "",
+            indent(generateEnumToDenseValue()),
+            "",
+            indent(generateEnumFromDenseValue(className)),
+            "",
+            indent(generateEnumToDenseJson()),
+            "",
+            indent(generateEnumFromDenseJson(className)),
+            "}",
+            "",
+        ].join("\n"),
+    };
+}
+function generateEnumConstructors(variants, context) {
+    return variants
+        .filter((variant) => !isRemovedDeclaration(variant))
+        .map((variant) => {
+        if (variant.type === undefined) {
+            return [
+                `public static function ${toPropertyName(variant.name)}(): self`,
+                "{",
+                `    return new self(EnumValue::constant('${variant.name}'));`,
+                "}",
+            ].join("\n");
+        }
+        return [
+            `public static function ${toPropertyName(variant.name)}(${phpType(variant.type, context)} $value): self`,
+            "{",
+            `    return new self(EnumValue::wrapper('${variant.name}', $value));`,
+            "}",
+        ].join("\n");
+    })
+        .join("\n\n");
+}
+function generateEnumSkirType(record, context) {
+    const entries = collectDeclarations(record)
+        .map((declaration) => {
+        if (isRemovedDeclaration(declaration)) {
+            return null;
+        }
+        if (declaration.type === undefined) {
+            return `    Variant::constant('${declaration.name}', ${declaration.number}),`;
+        }
+        return `    Variant::wrapper('${declaration.name}', ${declaration.number}, ${runtimeTypeExpression(declaration.type, context)}),`;
+    })
+        .filter((entry) => entry !== null)
+        .join("\n");
+    return [
+        "public static function skirType(): Type",
+        "{",
+        "    return Type::enum([",
+        entries,
+        "    ]);",
+        "}",
+    ].join("\n");
+}
+function generateEnumAccessors() {
+    return [
+        "public function name(): string",
+        "{",
+        "    return $this->value->name;",
+        "}",
+        "",
+        "public function payload(): mixed",
+        "{",
+        "    return $this->value->value;",
+        "}",
+    ].join("\n");
+}
+function generateEnumToSkirValue() {
+    return [
+        "public function toSkirValue(): EnumValue",
+        "{",
+        "    return $this->value;",
+        "}",
+    ].join("\n");
+}
+function generateEnumFromSkirValue(className) {
+    return [
+        `public static function fromSkirValue(EnumValue $value): ${className}`,
+        "{",
+        "    return new self($value);",
+        "}",
+    ].join("\n");
+}
+function generateEnumToDenseValue() {
+    return [
+        "/** @return int|array<int, mixed> */",
+        "public function toDenseValue(): int|array",
+        "{",
+        "    return DenseJson::encode(self::skirType(), $this->value);",
+        "}",
+    ].join("\n");
+}
+function generateEnumFromDenseValue(className) {
+    return [
+        "/** @param int|array<int, mixed> $value */",
+        `public static function fromDenseValue(int|array $value): ${className}`,
+        "{",
+        "    return new self(DenseJson::decode(self::skirType(), $value));",
+        "}",
+    ].join("\n");
+}
+function generateEnumToDenseJson() {
+    return [
+        "public function toDenseJson(): string",
+        "{",
+        "    return DenseJson::toJson(self::skirType(), $this->value);",
+        "}",
+    ].join("\n");
+}
+function generateEnumFromDenseJson(className) {
+    return [
+        `public static function fromDenseJson(string $json): ${className}`,
+        "{",
+        "    return new self(DenseJson::fromJson(self::skirType(), $json));",
+        "}",
+    ].join("\n");
+}
+function generateMethodsFile(context, methods) {
+    const runtimeImports = [
+        "Skir\\Runtime\\MethodDescriptor",
+    ];
+    const fileContext = fileOutputContext(context, "SkirMethods", runtimeImports);
+    const descriptors = methods.map((method) => generateMethodDescriptor(method, fileContext)).join("\n\n");
+    return {
+        path: outputPath(context, "SkirMethods.php"),
+        code: [
+            "<?php",
+            "",
+            "declare(strict_types=1);",
+            "",
+            `namespace ${context.namespace};`,
+            "",
+            ...generateUseStatements(fileContext, runtimeImports),
+            "",
+            "final readonly class SkirMethods",
+            "{",
+            indent(generateAllMethods(methods)),
+            "",
+            indent(descriptors),
+            "}",
+            "",
+        ].join("\n"),
+    };
+}
+function generateMethodEnumFile(context, methods) {
+    const runtimeImports = [
+        "Skir\\Runtime\\MethodDescriptor",
+        "Skir\\Server\\Contracts\\SkirMethodReference",
+    ];
+    const className = methodEnumClassName(context);
+    const fileContext = fileOutputContext(context, className, runtimeImports);
+    const cases = methods.map((method) => `case ${toClassName(tokenText(method.name))};`).join("\n");
+    const matches = methods
+        .map((method) => `self::${toClassName(tokenText(method.name))} => SkirMethods::${toPropertyName(tokenText(method.name))}(),`)
+        .join("\n");
+    return {
+        path: outputPath(context, `${className}.php`),
+        code: [
+            "<?php",
+            "",
+            "declare(strict_types=1);",
+            "",
+            `namespace ${context.namespace};`,
+            "",
+            ...generateUseStatements(fileContext, runtimeImports),
+            "",
+            `enum ${className} implements SkirMethodReference`,
+            "{",
+            indent(cases),
+            "",
+            indent([
+                "public function descriptor(): MethodDescriptor",
+                "{",
+                "    return match ($this) {",
+                indent(indent(matches)),
+                "    };",
+                "}",
+            ].join("\n")),
+            "}",
+            "",
+        ].join("\n"),
+    };
+}
+function generateAllMethods(methods) {
+    return [
+        "/** @return array<string, MethodDescriptor> */",
+        "public static function all(): array",
+        "{",
+        "    return [",
+        ...methods.map((method) => `        '${tokenText(method.name)}' => self::${toPropertyName(tokenText(method.name))}(),`),
+        "    ];",
+        "}",
+    ].join("\n");
+}
+function generateMethodDescriptor(method, context) {
+    return [
+        `public static function ${toPropertyName(tokenText(method.name))}(): MethodDescriptor`,
+        "{",
+        "    return new MethodDescriptor(",
+        `        name: '${tokenText(method.name)}',`,
+        `        number: ${method.number},`,
+        `        requestType: ${runtimeTypeExpression(method.requestType ?? "string", context)},`,
+        `        responseType: ${runtimeTypeExpression(method.responseType ?? "string", context)},`,
+        "    );",
+        "}",
+    ].join("\n");
+}
+function generateClientFile(context, methods) {
+    const runtimeImports = [
+        "Skir\\Client\\SkirClient",
+    ];
+    const fileContext = fileOutputContext(context, "SkirRpcClient", runtimeImports);
+    const clientMethods = methods.map((method) => generateClientMethod(method, fileContext)).join("\n\n");
+    return {
+        path: outputPath(context, "SkirRpcClient.php"),
+        code: [
+            "<?php",
+            "",
+            "declare(strict_types=1);",
+            "",
+            `namespace ${context.namespace};`,
+            "",
+            ...generateUseStatements(fileContext, runtimeImports),
+            "",
+            "final readonly class SkirRpcClient",
+            "{",
+            indent(generateClientConstructor()),
+            "",
+            indent(clientMethods),
+            "}",
+            "",
+        ].join("\n"),
+    };
+}
+function generateClientConstructor() {
+    return [
+        "public function __construct(",
+        "    private SkirClient $client,",
+        ") {}",
+    ].join("\n");
+}
+function generateClientMethod(method, context) {
+    const methodName = toPropertyName(tokenText(method.name));
+    const requestType = method.requestType ?? "string";
+    const responseType = method.responseType ?? "string";
+    const request = valueToArrayExpression(requestType, "$request", context);
+    const response = valueFromArrayExpression(responseType, "$response", context);
+    return [
+        `public function ${methodName}(${phpType(requestType, context)} $request): ${phpType(responseType, context)}`,
+        "{",
+        `    $response = $this->client->invoke(SkirMethods::${methodName}(), ${request});`,
+        "",
+        `    return ${response};`,
+        "}",
+    ].join("\n");
+}
+function generateProceduresFile(context, methods) {
+    const runtimeImports = [
+        "Skir\\Server\\SkirContext",
+    ];
+    const fileContext = fileOutputContext(context, "SkirProcedures", runtimeImports);
+    const procedureMethods = methods.map((method) => generateProcedureMethod(method, fileContext)).join("\n\n");
+    return {
+        path: outputPath(context, "SkirProcedures.php"),
+        code: [
+            "<?php",
+            "",
+            "declare(strict_types=1);",
+            "",
+            `namespace ${context.namespace};`,
+            "",
+            ...generateUseStatements(fileContext, runtimeImports),
+            "",
+            "interface SkirProcedures",
+            "{",
+            indent(procedureMethods),
+            "}",
+            "",
+        ].join("\n"),
+    };
+}
+function generateProcedureMethod(method, context) {
+    const methodName = toPropertyName(tokenText(method.name));
+    const requestType = method.requestType ?? "string";
+    const responseType = method.responseType ?? "string";
+    return `public function ${methodName}(${phpType(requestType, context)} $request, SkirContext $context): ${phpType(responseType, context)};`;
+}
+function generateAbstractProceduresFile(context, methods) {
+    const runtimeImports = [
+        "Skir\\Server\\ProcedureProvider",
+        "Skir\\Server\\SkirContext",
+        "Skir\\Server\\SkirServer",
+    ];
+    const fileContext = fileOutputContext(context, "AbstractSkirProcedures", runtimeImports);
+    const procedureMethods = methods.map((method) => generateAbstractProcedureMethod(method, fileContext)).join("\n\n");
+    const registrations = methods.map((method) => generateProcedureRegistration(method, fileContext, "$this")).join("\n\n");
+    return {
+        path: outputPath(context, "AbstractSkirProcedures.php"),
+        code: [
+            "<?php",
+            "",
+            "declare(strict_types=1);",
+            "",
+            `namespace ${context.namespace};`,
+            "",
+            ...generateUseStatements(fileContext, runtimeImports),
+            "",
+            "abstract class AbstractSkirProcedures implements ProcedureProvider",
+            "{",
+            indent(procedureMethods),
+            "",
+            indent([
+                "public function register(SkirServer $server): void",
+                "{",
+                indent(registrations),
+                "}",
+            ].join("\n")),
+            "}",
+            "",
+        ].join("\n"),
+    };
+}
+function generateAbstractProcedureMethod(method, context) {
+    const methodName = toPropertyName(tokenText(method.name));
+    const requestType = method.requestType ?? "string";
+    const responseType = method.responseType ?? "string";
+    return `abstract public function ${methodName}(${phpType(requestType, context)} $request, SkirContext $context): ${phpType(responseType, context)};`;
+}
+function generateProcedureProviderFile(context, methods) {
+    const runtimeImports = [
+        "Skir\\Server\\ProcedureProvider",
+        "Skir\\Server\\SkirContext",
+        "Skir\\Server\\SkirServer",
+    ];
+    const fileContext = fileOutputContext(context, "SkirProcedureProvider", runtimeImports);
+    const registrations = methods.map((method) => generateProcedureRegistration(method, fileContext)).join("\n\n");
+    return {
+        path: outputPath(context, "SkirProcedureProvider.php"),
+        code: [
+            "<?php",
+            "",
+            "declare(strict_types=1);",
+            "",
+            `namespace ${context.namespace};`,
+            "",
+            ...generateUseStatements(fileContext, runtimeImports),
+            "",
+            "final readonly class SkirProcedureProvider implements ProcedureProvider",
+            "{",
+            indent(generateProcedureProviderConstructor()),
+            "",
+            indent([
+                "public function register(SkirServer $server): void",
+                "{",
+                indent(registrations),
+                "}",
+            ].join("\n")),
+            "}",
+            "",
+        ].join("\n"),
+    };
+}
+function generateProcedureProviderConstructor() {
+    return [
+        "public function __construct(",
+        "    private SkirProcedures $procedures,",
+        ") {}",
+    ].join("\n");
+}
+function generateProcedureRegistration(method, context, handlerTarget = "$this->procedures") {
+    const methodName = toPropertyName(tokenText(method.name));
+    const requestType = method.requestType ?? "string";
+    const responseType = method.responseType ?? "string";
+    const request = valueFromArrayExpression(requestType, "$request", context);
+    const response = valueToArrayExpression(responseType, "$response", context);
+    return [
+        `$server->addMethod(SkirMethods::${methodName}(), function (mixed $request, SkirContext $context): mixed {`,
+        `    $response = ${handlerTarget}->${methodName}(${request}, $context);`,
+        "",
+        `    return ${response};`,
+        "});",
+    ].join("\n");
+}
+function collectStructFields(record) {
+    return collectDeclarations(record, "string")
+        .filter((field) => !isRemovedDeclaration(field))
+        .map((field) => ({
+        name: field.name,
+        number: field.number,
+        type: field.type ?? "string",
+    }));
+}
+function collectDeclarations(record, defaultMissingType) {
+    const declarations = [];
+    for (const field of record.fields ?? []) {
+        if (field.kind === "removed") {
+            declarations.push({ kind: "removed", number: field.number });
+            continue;
+        }
+        declarations.push({
+            name: tokenText(field.name),
+            number: field.number,
+            type: field.type ?? defaultMissingType,
+        });
+    }
+    for (const removedNumber of record.removedNumbers ?? []) {
+        if (!declarations.some((declaration) => declaration.number === removedNumber)) {
+            declarations.push({ kind: "removed", number: removedNumber });
+        }
+    }
+    return declarations.sort((left, right) => left.number - right.number);
+}
+function isStruct(record) {
+    return record.recordType === "struct" || record.kind === "struct";
+}
+function isEnum(record) {
+    return record.recordType === "enum" || record.kind === "enum";
+}
+function buildClassNameRegistry(rootNamespace, modules) {
+    const candidates = modules.flatMap((module) => (module.records ?? []).map((record, index) => {
+        const modulePath = modulePathForRecord(module, record);
+        const baseClassName = "record" in record
+            ? classNameForRecordLocation(record)
+            : classNameForRecord(record);
+        return {
+            identity: recordIdentity(module, record, index),
+            recordKey: recordKeyForRecord(record),
+            namespace: outputContextForModulePath(rootNamespace, modulePath).namespace,
+            modulePath,
+            baseClassName,
+        };
+    }));
+    const candidatesByClass = new Map();
+    for (const candidate of candidates) {
+        const groupKey = `${candidate.namespace}\\${candidate.baseClassName}`;
+        const existingCandidates = candidatesByClass.get(groupKey);
+        if (existingCandidates !== undefined) {
+            existingCandidates.push(candidate);
+        }
+        else {
+            candidatesByClass.set(groupKey, [candidate]);
+        }
+    }
+    const namesByIdentity = new Map();
+    const namesByRecordKey = new Map();
+    for (const groupedCandidates of candidatesByClass.values()) {
+        for (const candidate of groupedCandidates) {
+            const className = groupedCandidates.length > 1
+                ? `${moduleClassPrefix(candidate.modulePath)}${candidate.baseClassName}`
+                : candidate.baseClassName;
+            namesByIdentity.set(candidate.identity, className);
+            if (candidate.recordKey !== undefined) {
+                namesByRecordKey.set(candidate.recordKey, className);
+            }
+        }
+    }
+    return {
+        namesByIdentity,
+        namesByRecordKey,
+    };
+}
+function modulePathForRecord(module, record) {
+    if ("record" in record) {
+        return record.modulePath ?? module.path;
+    }
+    return module.path;
+}
+function recordIdentity(module, record, index) {
+    return recordKeyForRecord(record) ?? `${module.path}:${index}`;
+}
+function recordKeyForRecord(record) {
+    const recordKey = "record" in record
+        ? record.record.key
+        : record.key;
+    return typeof recordKey === "string" ? recordKey : undefined;
+}
+function classNameFromRegistry(classNames, identity, recordKey) {
+    if (classNames === undefined) {
+        return undefined;
+    }
+    if (typeof recordKey === "string") {
+        const className = classNames.namesByRecordKey.get(recordKey);
+        if (className !== undefined) {
+            return className;
+        }
+    }
+    if (identity !== undefined) {
+        return classNames.namesByIdentity.get(identity);
+    }
+    return undefined;
+}
+function moduleClassPrefix(modulePath) {
+    const moduleFileName = modulePath.split("/").at(-1) ?? modulePath;
+    const moduleName = moduleFileName.replace(/\.skir$/, "");
+    return toClassName(moduleName);
+}
+function normalizeRecord(record, module, index, classNames) {
+    if ("record" in record) {
+        return {
+            ...record.record,
+            phpClassName: classNameFromRegistry(classNames, recordIdentity(module, record, index), record.record.key) ?? classNameForRecordLocation(record),
+        };
+    }
+    return {
+        ...record,
+        phpClassName: classNameFromRegistry(classNames, recordIdentity(module, record, index), record.key) ?? record.phpClassName,
+    };
+}
+function isRemovedDeclaration(declaration) {
+    return "kind" in declaration && declaration.kind === "removed";
+}
+function phpType(type, context) {
+    const kind = typeKind(type);
+    if (kind === "bool") {
+        return "bool";
+    }
+    if (kind === "int32" || kind === "timestamp") {
+        return "int";
+    }
+    if (kind === "int64" || kind === "hash64") {
+        return "int|string";
+    }
+    if (kind === "float32" || kind === "float64") {
+        return "float";
+    }
+    if (kind === "string" || kind === "bytes") {
+        return "string";
+    }
+    if (kind === "array") {
+        return "array";
+    }
+    if (kind === "optional") {
+        return "?".concat(phpType(optionalInnerType(type), context));
+    }
+    if (kind === "record") {
+        return recordTypeClassName(type, context);
+    }
+    return "mixed";
+}
+function valueToArrayExpression(type, expression, context) {
+    const kind = typeKind(type);
+    if (kind === "record") {
+        if (isEnumRecordReference(type, context)) {
+            return `${expression}->toSkirValue()`;
+        }
+        return `${expression}->toArray()`;
+    }
+    if (kind === "optional") {
+        const innerType = optionalInnerType(type);
+        if (typeKind(innerType) === "record" || typeKind(innerType) === "array") {
+            return `${expression} === null ? null : ${valueToArrayExpression(innerType, expression, context)}`;
+        }
+        return expression;
+    }
+    if (kind === "array") {
+        const itemType = arrayItemType(type);
+        if (typeKind(itemType) === "record" || typeKind(itemType) === "optional" || typeKind(itemType) === "array") {
+            return `array_map(fn (mixed $item): mixed => ${valueToArrayExpression(itemType, "$item", context)}, ${expression})`;
+        }
+    }
+    return expression;
+}
+function valueFromArrayExpression(type, expression, context) {
+    const kind = typeKind(type);
+    if (kind === "record") {
+        if (isEnumRecordReference(type, context)) {
+            return `${recordTypeClassName(type, context)}::fromSkirValue(${expression})`;
+        }
+        return `${recordTypeClassName(type, context)}::fromArray(${expression})`;
+    }
+    if (kind === "optional") {
+        const innerType = optionalInnerType(type);
+        if (typeKind(innerType) === "record" || typeKind(innerType) === "array") {
+            return `${expression} === null ? null : ${valueFromArrayExpression(innerType, expression, context)}`;
+        }
+        return expression;
+    }
+    if (kind === "array") {
+        const itemType = arrayItemType(type);
+        if (typeKind(itemType) === "record" || typeKind(itemType) === "optional" || typeKind(itemType) === "array") {
+            return `array_map(fn (mixed $item): mixed => ${valueFromArrayExpression(itemType, "$item", context)}, ${expression})`;
+        }
+    }
+    return expression;
+}
+function runtimeTypeExpression(type, context) {
+    const kind = typeKind(type);
+    if (kind === "array") {
+        return `Type::array(${runtimeTypeExpression(arrayItemType(type), context)})`;
+    }
+    if (kind === "optional") {
+        return `Type::optional(${runtimeTypeExpression(optionalInnerType(type), context)})`;
+    }
+    if (kind === "record") {
+        return `${recordTypeClassName(type, context)}::skirType()`;
+    }
+    return `Type::${kind}()`;
+}
+function typeKind(type) {
+    if (typeof type === "string") {
+        return type;
+    }
+    if (type.kind === "primitive") {
+        return type.primitive ?? "string";
+    }
+    return type.kind;
+}
+function arrayItemType(type) {
+    if (typeof type !== "string" && type.kind === "array" && type.item !== undefined) {
+        return type.item;
+    }
+    return "string";
+}
+function optionalInnerType(type) {
+    if (typeof type !== "string" && type.kind === "optional" && type.other !== undefined) {
+        return type.other;
+    }
+    return "string";
+}
+function recordTypeClassName(type, context) {
+    if (typeof type === "string") {
+        throw new Error("String primitive types cannot be used as record references.");
+    }
+    if (typeof type.key === "string" && context.recordMap !== undefined) {
+        const recordLocation = context.recordMap.get(type.key);
+        if (recordLocation !== undefined) {
+            return classNameForRecordReference(context, recordLocation);
+        }
+    }
+    if (type.name !== undefined) {
+        return toClassName(tokenText(type.name));
+    }
+    if (type.nameParts !== undefined && type.nameParts.length > 0) {
+        return classNameFromParts(type.nameParts.map((part) => recordNamePartText(part)));
+    }
+    throw new Error("Skir record reference is missing a name.");
+}
+function isEnumRecordReference(type, context) {
+    if (typeof type === "string") {
+        return false;
+    }
+    if (type.kind !== "record") {
+        return false;
+    }
+    if (type.recordType === "enum") {
+        return true;
+    }
+    if (typeof type.key !== "string") {
+        return false;
+    }
+    return context.recordMap?.get(type.key)?.record.recordType === "enum";
+}
+function classNameForRecord(record) {
+    return record.phpClassName ?? toClassName(tokenText(record.name));
+}
+function classNameForRecordReference(context, recordLocation) {
+    const className = classNameFromRegistry(context.classNames, undefined, recordLocation.record.key) ?? classNameForRecordLocation(recordLocation);
+    const recordContext = outputContextForModulePath(context.rootNamespace, recordLocation.modulePath ?? "", context.recordMap, context.classNames);
+    if (recordContext.namespace === context.namespace) {
+        return className;
+    }
+    return importedClassName(context, `${recordContext.namespace}\\${className}`);
+}
+function outputContextForModule(rootNamespace, module, recordMap, classNames) {
+    return outputContextForModulePath(rootNamespace, module.path, recordMap, classNames);
+}
+function outputContextForModulePath(rootNamespace, modulePath, recordMap, classNames) {
+    const directoryParts = modulePath
+        .split("/")
+        .slice(0, -1)
+        .map((part) => toClassName(part))
+        .filter((part) => part !== "");
+    if (directoryParts.length === 0) {
+        return {
+            rootNamespace,
+            namespace: rootNamespace,
+            pathPrefix: "",
+            recordMap,
+            classNames,
+        };
+    }
+    return {
+        rootNamespace,
+        namespace: [rootNamespace, ...directoryParts].join("\\"),
+        pathPrefix: directoryParts.join("/"),
+        recordMap,
+        classNames,
+    };
+}
+function outputPath(context, fileName) {
+    if (context.pathPrefix === "") {
+        return fileName;
+    }
+    return `${context.pathPrefix}/${fileName}`;
+}
+function methodEnumClassName(context) {
+    if (context.pathPrefix === "") {
+        return "SkirMethod";
+    }
+    return `${context.pathPrefix.split("/").map((part) => toClassName(part)).join("")}SkirMethod`;
+}
+function fileOutputContext(context, className, runtimeImports) {
+    const reservedNames = new Set([
+        className,
+        ...runtimeImports.map((importName) => shortClassName(importName)),
+    ]);
+    return {
+        ...context,
+        imports: {
+            reservedNames,
+            imports: new Map(),
+        },
+    };
+}
+function generateUseStatements(context, runtimeImports) {
+    const generatedImports = Array.from(context.imports?.imports.values() ?? []).sort();
+    return [
+        ...runtimeImports,
+        ...generatedImports,
+    ].map((importName) => `use ${importName};`);
+}
+function importedClassName(context, fullyQualifiedClassName) {
+    const shortName = shortClassName(fullyQualifiedClassName);
+    if (context.imports === undefined) {
+        return `\\${fullyQualifiedClassName}`;
+    }
+    if (context.imports.reservedNames.has(shortName)) {
+        return `\\${fullyQualifiedClassName}`;
+    }
+    const existingImport = context.imports.imports.get(shortName);
+    if (existingImport === undefined) {
+        context.imports.imports.set(shortName, fullyQualifiedClassName);
+        return shortName;
+    }
+    if (existingImport === fullyQualifiedClassName) {
+        return shortName;
+    }
+    return `\\${fullyQualifiedClassName}`;
+}
+function shortClassName(fullyQualifiedClassName) {
+    return fullyQualifiedClassName.split("\\").at(-1) ?? fullyQualifiedClassName;
+}
+function classNameForRecordLocation(record) {
+    if (record.recordAncestors !== undefined && record.recordAncestors.length > 0) {
+        return classNameFromParts(record.recordAncestors.map((ancestor) => tokenText(ancestor.name)));
+    }
+    return toClassName(tokenText(record.record.name));
+}
+function classNameFromParts(parts) {
+    return parts.map((part) => toClassName(part)).join("");
+}
+function recordNamePartText(part) {
+    if (typeof part === "string") {
+        return part;
+    }
+    if ("token" in part) {
+        return tokenText(part.token);
+    }
+    return tokenText(part);
+}
+function toClassName(name) {
+    return name
+        .split(/[_\-\s]+/)
+        .filter(Boolean)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join("");
+}
+function toPropertyName(name) {
+    const className = toClassName(name);
+    return className.charAt(0).toLowerCase() + className.slice(1);
+}
+function tokenText(token) {
+    return typeof token === "string" ? token : token.text;
+}
+function indent(code) {
+    return code
+        .split("\n")
+        .map((line) => (line === "" ? line : `    ${line}`))
+        .join("\n");
+}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+import { type CodeGenerator } from "skir-internal";
+import { z } from "zod";
+import { generatePhpFiles } from "./generator.js";
+declare const Config: z.ZodObject<{
+    namespace: z.ZodDefault<z.ZodString>;
+}, z.core.$strict>;
+type Config = z.infer<typeof Config>;
+declare class PhpGenerator implements CodeGenerator<Config> {
+    readonly id = "skir-php-generator";
+    readonly configType: z.ZodObject<{
+        namespace: z.ZodDefault<z.ZodString>;
+    }, z.core.$strict>;
+    generateCode(input: CodeGenerator.Input<Config>): CodeGenerator.Output;
+}
+export declare const GENERATOR: PhpGenerator;
+export { generatePhpFiles };

package/dist/index.js

@@ -0,0 +1,16 @@
+import { z } from "zod";
+import { generatePhpFiles } from "./generator.js";
+const Config = z.strictObject({
+    namespace: z.string().default("App\\Skir"),
+});
+class PhpGenerator {
+    id = "skir-php-generator";
+    configType = Config;
+    generateCode(input) {
+        return {
+            files: generatePhpFiles(input),
+        };
+    }
+}
+export const GENERATOR = new PhpGenerator();
+export { generatePhpFiles };

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "skir-php-generator",
+  "version": "0.1.0",
+  "description": "Skir code generator for standard PHP data objects.",
+  "type": "module",
+  "license": "MIT",
+  "author": {
+    "name": "Maxim Kerstens",
+    "email": "maxim.kerstens@gmail.com"
+  },
+  "homepage": "https://github.com/php-skir/skir-php-generator#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/php-skir/skir-php-generator.git"
+  },
+  "bugs": {
+    "url": "https://github.com/php-skir/skir-php-generator/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "php",
+    "rpc",
+    "skir",
+    "skir-generator"
+  ],
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "pack:dry-run": "npm pack --dry-run --cache .npm-cache",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "skir-internal": "^0.2.21",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "skir": "^1.2.19",
+    "typescript": "^5.9.0",
+    "vitest": "^4.0.0"
+  }
+}