@redocly/client-generator 0.3.8 → 0.4.0

package/eject-assets/generators/php/index.ts

@@ -0,0 +1,237 @@
+// Ejected from @redocly/client-generator@0.4.0 — the built-in "php" generator.
+// This file is yours: edit freely; the generated client stays machine-owned and is
+// rebuilt by `redocly generate-client`. Newer generator versions merge in with
+// `redocly eject-generator php --update`.
+// The built-in `php` generator — the third non-TypeScript library entry, authored
+// with the language-neutral toolkit only (same dogfooding invariant as python/go,
+// pinned by the guard test). Output is a single PHP >= 8.1 file over the curl
+// extension: promoted-constructor classes with fromArray/toArray hydration, native
+// backed enums, match-based discriminator dispatchers, and a Client over the
+// embedded runtime. Exceptions are the error mode (`errorMode` does not apply).
+
+import {
+  type CodeSample,
+  type Generator,
+  identifierFor,
+  jsonSuccessSchema,
+  type NeutralPaginationRule,
+  type OperationModel,
+  paginationItemSchema,
+  renderReferencePage,
+  type SampleContext,
+  sseResponse,
+} from '@redocly/client-generator';
+import { PhpPrinter } from '@redocly/client-generator/printers/php';
+import { PHP_RUNTIME_SOURCE } from '@redocly/client-generator/runtime-sources';
+
+import { writeServers } from './client.ts';
+import { phpPaginationLiteral, phpSecurityLiteral } from './descriptor.ts';
+import { hydration, renderPhpModels } from './models.ts';
+import { methodIdents, methodName, PHP, phpString, propertyName } from './naming.ts';
+import { writePhpMethod } from './operations.ts';
+import { writePhpPaginationWrappers } from './pagination.ts';
+import { phpType } from './types.ts';
+
+export { renderPhpModels } from './models.ts';
+export { phpType } from './types.ts';
+
+/** Drop the standalone header (<?php, declare, namespace, leading comments) for stitching. */
+function stripPhpHeader(source: string): string {
+  const lines = source.split('\n');
+  let start = 0;
+  for (let index = 0; index < lines.length; index++) {
+    const line = lines[index].trim();
+    if (line.startsWith('namespace ')) {
+      start = index + 1;
+      break;
+    }
+  }
+  return lines.slice(start).join('\n').trim();
+}
+
+/** The whole generated file: namespace + models + embedded runtime + operations + Client. */
+export const phpGenerator: Generator = ({ model, output, banner, emit, pagination }) => {
+  const printer = new PhpPrinter();
+  const dateType = emit.dateType ?? 'string';
+  const namespace = identifierFor(model.title, { style: 'pascal', reserved: PHP });
+  printer.line('<?php');
+  printer.blank();
+  printer.line(
+    `// Code generated by @redocly/client-generator (php) from ${phpString(model.title)} ${model.version}. DO NOT EDIT.`
+  );
+  printer.line(
+    '// Regenerate with `redocly generate-client`. PHP >= 8.1, curl extension — zero Composer dependencies.'
+  );
+  printer.blank();
+  printer.line('declare(strict_types=1);');
+  printer.blank();
+  printer.line(`namespace ${namespace};`);
+  printer.blank();
+  printer.line(renderPhpModels(model, dateType));
+  writeServers(printer, model);
+  if (emit.runtime === 'module') {
+    // The runtime file re-declares this same namespace, so the require binds the
+    // exact names the inline stitching would have defined at this position.
+    printer.line('// ─── Runtime (a real file beside this one, written by the same run) ───');
+    printer.line("require_once __DIR__ . '/runtime.php';");
+    printer.blank();
+  } else {
+    printer.line('// ─── Embedded runtime (@redocly/client-generator php runtime) ───');
+    printer.line(stripPhpHeader(PHP_RUNTIME_SOURCE));
+    printer.blank();
+  }
+
+  const operations = model.services.flatMap((service) => service.operations);
+  const idents = methodIdents(model);
+  // Pagination arrives RESOLVED from the pipeline — one fit-verified answer per run.
+  const paginationRules = new Map<string, NeutralPaginationRule>();
+  for (const op of operations) {
+    const spec = pagination?.get(op.name)?.spec;
+    if (spec !== undefined) paginationRules.set(op.name, spec);
+  }
+
+  printer.block(
+    'const OPERATIONS = [',
+    () => {
+      for (const op of operations) {
+        const id = op.specName ?? op.name;
+        const security = phpSecurityLiteral(op, model);
+        const rule = paginationRules.get(op.name);
+        const fields = [
+          `'id' => ${phpString(id)}`,
+          `'method' => ${phpString(op.method.toUpperCase())}`,
+          `'path' => ${phpString(op.path)}`,
+          ...(security !== undefined ? [`'security' => ${security}`] : []),
+          ...(rule !== undefined ? [`'pagination' => ${phpPaginationLiteral(rule)}`] : []),
+        ];
+        printer.line(`${phpString(id)} => [${fields.join(', ')}],`);
+      }
+    },
+    '];'
+  );
+  printer.blank();
+
+  printer.doc('Client', `Client for ${model.title} (${model.version}).`);
+  // Not final: PHP test suites mock concrete classes (createMock(Client::class)).
+  printer.line('class Client');
+  printer.block(
+    '{',
+    () => {
+      printer.line('public function __construct(private Config $config)');
+      printer.block(
+        '{',
+        () => {
+          printer.block(
+            "if ($this->config->serverUrl === '') {",
+            () => {
+              printer.line(
+                `$this->config->serverUrl = ${phpString(emit.serverUrl ?? model.serverUrl ?? '')};`
+              );
+            },
+            '}'
+          );
+        },
+        '}'
+      );
+      printer.blank();
+
+      for (const op of operations) {
+        const ident = idents.get(op.name)!;
+        writePhpMethod(printer, op, ident, model, dateType);
+        if (sseResponse(op) === undefined && (op.successResponseHeaders?.length ?? 0) > 0) {
+          writePhpMethod(printer, op, ident, model, dateType, true);
+        }
+        const rule = paginationRules.get(op.name);
+        if (rule === undefined) continue;
+        const success = jsonSuccessSchema(op);
+        const pageHydration =
+          success === undefined ? undefined : hydration(success, '$page', model, dateType);
+        const element = paginationItemSchema(success, rule.items, model);
+        const itemHydration =
+          element === undefined ? undefined : hydration(element, '$item', model, dateType);
+        writePhpPaginationWrappers(
+          printer,
+          op,
+          ident,
+          model,
+          dateType,
+          pageHydration,
+          itemHydration,
+          rule.items,
+          element === undefined ? 'mixed' : phpType(element, model, dateType)
+        );
+      }
+    },
+    '}'
+  );
+
+  const entry = { path: output.path.replace(/\.[^.\\/]+$/, '.php'), content: printer.toString() };
+  if (emit.runtime !== 'module') return [entry];
+  // The runtime, verbatim except its namespace: rewritten to the client's, so one
+  // namespace spans both files and every bare reference resolves unchanged.
+  const header = banner.map((line) => `// ${line}`).join('\n');
+  const runtimeSource = PHP_RUNTIME_SOURCE.replace(/^namespace .*$/m, `namespace ${namespace};`)
+    .replace(/^<\?php\n/, `<?php\n\n${header}\n`)
+    .trimEnd();
+  return [
+    entry,
+    { path: entry.path.replace(/[^\\/]+$/, 'runtime.php'), content: `${runtimeSource}\n` },
+  ];
+};
+
+/** One idiomatic PHP call per operation — feeds `x-codeSamples` for docs. */
+export function phpSample(op: OperationModel, ctx: SampleContext): CodeSample {
+  const args = [
+    ...op.pathParams.map((param) => `${phpString(`<${propertyName(param.name)}>`)}`),
+    ...(op.requestBody ? ['$body'] : []),
+    ...(op.queryParams.length > 0
+      ? [`${propertyName(op.queryParams[0].name)}: ${phpString('<value>')}`]
+      : []),
+  ];
+  const namespace = identifierFor(ctx.model.title, { style: 'pascal', reserved: PHP });
+  // The file this run writes, so the snippet requires something that exists.
+  const file = ctx.outputPath.replace(/^.*[\\/]/, '').replace(/\.[^.]+$/, '.php');
+  return {
+    lang: 'php',
+    label: 'PHP SDK',
+    source: `require '${file}';\n\nuse ${namespace}\\{Client, Config};\n\n$client = new Client(new Config());\n$result = $client->${methodIdents(ctx.model).get(op.name) ?? methodName(op)}(${args.join(', ')});\n`,
+  };
+}
+
+/**
+ * The SDK's own reference page, written when `client.docs` is on. The call snippets come
+ * from `phpSample` — this generator's own hook — so the page can only ever show the syntax
+ * of the SDK beside it, and ejecting this generator takes the page with it.
+ */
+export const phpDocs: Generator = ({ model, output, emit, pagination }) => [
+  {
+    path: output.path.replace(/\.[^.\\/]+$/, '.php.md'),
+    content: renderReferencePage(model, {
+      title: `${model.title} PHP SDK reference`,
+      frontmatter: emit.docsFrontmatter === true,
+      language: {
+        name: 'php',
+        label: 'PHP',
+        fence: 'php',
+        requires: 'The SDK needs the curl extension.',
+      },
+      sample: (op) => phpSample(op, { model, emit, outputPath: output.path }),
+      paginated: new Set(pagination?.keys() ?? []),
+    }),
+  },
+];
+
+export default {
+  name: 'php',
+  run: phpGenerator,
+  sample: phpSample,
+  docs: phpDocs,
+  errorModes: ["throw"],
+  notApplicable: {
+    "outputMode": "it always emits one self-contained file",
+    "runtime": "the runtime is always embedded in the generated file",
+    "argsStyle": "inputs follow the target language's own idiom",
+    "importExt": "the generated file has no relative imports"
+  },
+  requiresGenerator: '^0.4.0',
+};

package/eject-assets/generators/php/models.ts

@@ -0,0 +1,275 @@
+// Ejected from @redocly/client-generator@0.4.0 — the built-in "php" generator.
+// This file is yours: edit freely; the generated client stays machine-owned and is
+// rebuilt by `redocly generate-client`. Newer generator versions merge in with
+// `redocly eject-generator php --update`.
+// The `models` stage: named schemas as promoted-constructor classes with
+// fromArray/toArray hydration, native backed enums, and match-based union
+// dispatchers — plus the wire↔typed value expressions the methods reuse.
+
+import {
+  type ApiModel,
+  type DateType,
+  deref,
+  discriminatorCases,
+  enumValues,
+  flattenAllOf,
+  type PropertyModel,
+  type SchemaModel,
+  uniqueIdentifiers,
+  unwrapNullable,
+} from '@redocly/client-generator';
+import { PhpPrinter } from '@redocly/client-generator/printers/php';
+
+import { className, PHP, phpString, propertyName } from './naming.ts';
+import { classify, isDateFormat, phpNullable, phpType } from './types.ts';
+
+/** True when the named schema renders as an `unmarshalX` union dispatcher. */
+function isDiscriminatedUnion(name: string, model: ApiModel): boolean {
+  const named = model.schemas.find((candidate) => candidate.name === name);
+  return named !== undefined && discriminatorCases(named.schema, model) !== undefined;
+}
+
+/** Wire value → typed value expression, or undefined when the raw value is already right. */
+export function hydration(
+  schema: SchemaModel,
+  expr: string,
+  model: ApiModel,
+  // Required on purpose: a defaulted `'string'` let a call site forget it, and the method
+  // then returned a raw string where its own signature declared `\DateTimeImmutable`.
+  dateType: DateType
+): string | undefined {
+  const bare = unwrapNullable(schema);
+  if (dateType === 'Date' && bare.kind === 'scalar' && bare.scalar === 'string') {
+    if (isDateFormat(bare)) return `new \\DateTimeImmutable(${expr})`;
+  }
+  if (bare.kind === 'omit')
+    return hydration({ kind: 'ref', name: bare.base }, expr, model, dateType);
+  if (bare.kind === 'ref') {
+    const kind = classify(bare.name, model);
+    if (kind === 'class') return `${className(bare.name)}::fromArray(${expr})`;
+    if (kind === 'enum') return `${className(bare.name)}::from(${expr})`;
+    if (isDiscriminatedUnion(bare.name, model)) return `unmarshal${className(bare.name)}(${expr})`;
+    const target = deref(bare, model);
+    return target === undefined ? undefined : hydration(target, expr, model, dateType);
+  }
+  if (bare.kind === 'array') {
+    const item = hydration(bare.items, '$item', model, dateType);
+    if (item === undefined) return undefined;
+    return `array_map(static fn ($item) => ${item}, ${expr})`;
+  }
+  if (bare.kind === 'record') {
+    const item = hydration(bare.value, '$item', model, dateType);
+    if (item === undefined) return undefined;
+    return `array_map(static fn ($item) => ${item}, ${expr})`;
+  }
+  return undefined;
+}
+
+/** Typed value → wire value expression, or undefined when it serializes as-is. */
+export function serialization(
+  schema: SchemaModel,
+  expr: string,
+  model: ApiModel,
+  dateType: DateType = 'string'
+): string | undefined {
+  const bare = unwrapNullable(schema);
+  if (dateType === 'Date' && bare.kind === 'scalar' && bare.scalar === 'string') {
+    // A date-only value must not gain a time component on the way out.
+    if (bare.metadata?.format === 'date') return `${expr}->format('Y-m-d')`;
+    if (bare.metadata?.format === 'date-time') {
+      return `${expr}->format(\\DateTimeInterface::ATOM)`;
+    }
+  }
+  if (bare.kind === 'omit') {
+    return serialization({ kind: 'ref', name: bare.base }, expr, model, dateType);
+  }
+  if (bare.kind === 'ref') {
+    const kind = classify(bare.name, model);
+    if (kind === 'class') return `${expr}->toArray()`;
+    if (kind === 'enum') return `${expr}->value`;
+    // A union value may be a hydrated member instance or a raw (default-case) array.
+    if (isDiscriminatedUnion(bare.name, model)) {
+      return `is_object(${expr}) ? ${expr}->toArray() : ${expr}`;
+    }
+    const target = deref(bare, model);
+    return target === undefined ? undefined : serialization(target, expr, model, dateType);
+  }
+  if (bare.kind === 'array' || bare.kind === 'record') {
+    const inner = bare.kind === 'array' ? bare.items : bare.value;
+    const item = serialization(inner, '$item', model, dateType);
+    if (item === undefined) return undefined;
+    return `array_map(static fn ($item) => ${item}, ${expr})`;
+  }
+  return undefined;
+}
+
+function writeClass(
+  printer: PhpPrinter,
+  name: string,
+  properties: PropertyModel[],
+  model: ApiModel,
+  dateType: DateType,
+  description?: string
+): void {
+  // PHP requires defaulted parameters after required ones.
+  const ordered = [
+    ...properties.filter((property) => property.required),
+    ...properties.filter((property) => !property.required),
+  ];
+  printer.doc(className(name), description);
+  printer.line(`final class ${className(name)}`);
+  printer.block(
+    '{',
+    () => {
+      printer.block(
+        'public function __construct(',
+        () => {
+          for (const property of ordered) {
+            const type = phpType(property.schema, model, dateType);
+            if (property.required) {
+              printer.line(`public ${type} ${'$'}${propertyName(property.name)},`);
+            } else {
+              const nullable = phpNullable(type);
+              printer.line(`public ${nullable} ${'$'}${propertyName(property.name)} = null,`);
+            }
+          }
+        },
+        ') {'
+      );
+      printer.line('}');
+      printer.blank();
+
+      printer.line('public static function fromArray(array $data): self');
+      printer.block(
+        '{',
+        () => {
+          printer.block(
+            'return new self(',
+            () => {
+              for (const property of ordered) {
+                const raw = `$data[${phpString(property.name)}]`;
+                const typed = hydration(property.schema, raw, model, dateType);
+                const php = propertyName(property.name);
+                if (property.required) {
+                  printer.line(`${php}: ${typed ?? raw},`);
+                } else if (typed === undefined) {
+                  printer.line(`${php}: ${raw} ?? null,`);
+                } else {
+                  printer.line(`${php}: isset(${raw}) ? ${typed} : null,`);
+                }
+              }
+            },
+            ');'
+          );
+        },
+        '}'
+      );
+      printer.blank();
+
+      printer.line('public function toArray(): array');
+      printer.block(
+        '{',
+        () => {
+          printer.line('$data = [];');
+          for (const property of ordered) {
+            const value = `$this->${propertyName(property.name)}`;
+            const wire = serialization(property.schema, value, model, dateType) ?? value;
+            if (property.required) {
+              printer.line(`$data[${phpString(property.name)}] = ${wire};`);
+            } else {
+              printer.block(
+                `if (${value} !== null) {`,
+                () => {
+                  printer.line(`$data[${phpString(property.name)}] = ${wire};`);
+                },
+                '}'
+              );
+            }
+          }
+          printer.line('return $data;');
+        },
+        '}'
+      );
+    },
+    '}'
+  );
+  printer.blank();
+}
+
+/** Render every named schema: classes (allOf flattened), native enums, union dispatchers. */
+export function renderPhpModels(model: ApiModel, dateType: DateType = 'string'): string {
+  const printer = new PhpPrinter();
+  for (const { name, schema } of model.schemas) {
+    const asEnum = enumValues(schema);
+    if (asEnum !== undefined && (asEnum.scalar === 'string' || asEnum.scalar === 'integer')) {
+      const backing = asEnum.scalar === 'string' ? 'string' : 'int';
+      printer.doc(className(name), schema.description);
+      printer.line(`enum ${className(name)}: ${backing}`);
+      printer.block(
+        '{',
+        () => {
+          // `1.5` and `15` fold to one pascal name; PHP rejects a duplicate case.
+          const members = uniqueIdentifiers(
+            asEnum.values.map((value) => String(value)),
+            { style: 'pascal', reserved: PHP }
+          );
+          asEnum.values.forEach((value, index) => {
+            const literal = typeof value === 'string' ? phpString(value) : String(value);
+            printer.line(`case ${members[index]} = ${literal};`);
+          });
+        },
+        '}'
+      );
+      printer.blank();
+      continue;
+    }
+    if (schema.kind === 'object' || schema.kind === 'intersection') {
+      const flat = flattenAllOf(schema, model);
+      if (flat !== undefined) {
+        writeClass(
+          printer,
+          name,
+          flat.properties,
+          model,
+          dateType,
+          flat.description ?? schema.description
+        );
+        continue;
+      }
+    }
+    const cases = discriminatorCases(schema, model);
+    if (cases !== undefined) {
+      const typeName = className(name);
+      const table = cases.cases
+        .map((entry) => `${entry.value} -> ${className(entry.schemaName)}`)
+        .join(', ');
+      printer.line(
+        `/** ${typeName} is a discriminated union (${phpString(cases.property)}): ${table}. */`
+      );
+      printer.line(`function unmarshal${typeName}(array $data): mixed`);
+      printer.block(
+        '{',
+        () => {
+          printer.block(
+            `return match ($data[${phpString(cases.property)}] ?? null) {`,
+            () => {
+              for (const entry of cases.cases) {
+                printer.line(
+                  `${phpString(entry.value)} => ${className(entry.schemaName)}::fromArray($data),`
+                );
+              }
+              printer.line('default => $data,');
+            },
+            '};'
+          );
+        },
+        '}'
+      );
+      printer.blank();
+      continue;
+    }
+    // Everything else (plain unions, aliases, records) has no PHP declaration;
+    // references resolve to the underlying type via phpType.
+  }
+  return printer.toString();
+}

package/eject-assets/generators/php/naming.ts

@@ -0,0 +1,51 @@
+// Ejected from @redocly/client-generator@0.4.0 — the built-in "php" generator.
+// This file is yours: edit freely; the generated client stays machine-owned and is
+// rebuilt by `redocly generate-client`. Newer generator versions merge in with
+// `redocly eject-generator php --update`.
+// The `naming` stage: the shared printer/naming instance, the string escaper, and
+// the collision-free class/property/method identifiers every other stage builds on.
+
+import {
+  type ApiModel,
+  identifierFor,
+  type OperationModel,
+  RESERVED_WORDS,
+  uniqueIdentifiers,
+} from '@redocly/client-generator';
+import { PhpPrinter } from '@redocly/client-generator/printers/php';
+
+export const PHP = RESERVED_WORDS.php;
+
+// Naming and escaping delegate to the printer — one implementation, one policy.
+export const naming = new PhpPrinter();
+
+export function className(name: string): string {
+  return naming.typeName(name);
+}
+
+export function propertyName(name: string): string {
+  return naming.memberName(name);
+}
+
+/** `'…'` with backslashes and quotes escaped — safe for any spec-supplied text. */
+export function phpString(value: string): string {
+  return naming.string(value);
+}
+
+export function methodName(op: OperationModel): string {
+  return identifierFor(op.name, { style: 'camel', reserved: PHP });
+}
+
+/**
+ * The method name for every operation, unique across the client — PHP fatals on a
+ * redeclared method, and two operationIds may camel-case to one name (`get-user`,
+ * `getUser`). Keyed by the IR name, which the sanitizer already made unique.
+ */
+export function methodIdents(model: ApiModel): Map<string, string> {
+  const operations = model.services.flatMap((service) => service.operations);
+  const names = uniqueIdentifiers(
+    operations.map((op) => op.name),
+    { style: 'camel', reserved: PHP }
+  );
+  return new Map(operations.map((op, index) => [op.name, names[index]]));
+}