@workos/oagen-emitters 0.3.0 → 0.5.0

package/src/php/resources.ts

@@ -1,5 +1,5 @@
 import type { Service, Operation, Model, EmitterContext, GeneratedFile, ResolvedOperation } from '@workos/oagen';
-import { planOperation, toCamelCase } from '@workos/oagen';
+import { planOperation, toCamelCase, toPascalCase } from '@workos/oagen';
 import { mapTypeRef, mapTypeRefForPHPDoc } from './type-map.js';
 import { className, fieldName, resolveMethodName } from './naming.js';
 import { isListWrapperModel } from './models.js';
@@ -9,6 +9,8 @@ import {
   lookupResolved,
   getOpDefaults,
   getOpInferFromClient,
+  collectGroupedParamNames,
+  collectBodyFieldTypes,
 } from '../shared/resolved-ops.js';
 import { generateWrapperMethods } from './wrappers.js';
 import { phpDocComment } from './utils.js';
@@ -50,8 +52,11 @@ export function generateResources(services: Service[], ctx: EmitterContext): Gen
     lines.push(`namespace ${ctx.namespacePascal}\\Service;`);
     lines.push('');
 
+    // Build resolved lookup early — used by both imports and method generation
+    const resolvedLookup = buildResolvedLookup(ctx);
+
     // Collect imports
-    const imports = collectImports(mergedService, ctx);
+    const imports = collectImports(mergedService, ctx, resolvedLookup);
     for (const imp of imports) {
       lines.push(`use ${imp};`);
     }
@@ -66,7 +71,6 @@ export function generateResources(services: Service[], ctx: EmitterContext): Gen
 
     // Track emitted method names to avoid duplicates
     const emittedMethods = new Set<string>();
-    const resolvedLookup = buildResolvedLookup(ctx);
     for (const op of operations) {
       const method = resolveMethodName(op, mergedService, ctx);
       if (emittedMethods.has(method)) continue;
@@ -89,11 +93,135 @@ export function generateResources(services: Service[], ctx: EmitterContext): Gen
       content: lines.join('\n'),
       overwriteExisting: true,
     });
+
+    // Generate variant class files for operations with parameter groups
+    for (const op of operations) {
+      if ((op.parameterGroups?.length ?? 0) > 0) {
+        files.push(...generateParameterGroupFiles(op, ctx, modelMap));
+      }
+    }
+  }
+
+  return files;
+}
+
+/**
+ * Check if an operation is a redirect endpoint that should construct a URL
+ * instead of making an HTTP request.
+ *
+ * Detection: GET endpoints with no response body (primitive unknown) and query
+ * params are redirect endpoints (e.g., SSO/OAuth authorize and logout flows).
+ * Also respects an explicit urlBuilder flag on the resolved operation and
+ * catches endpoints with 302 success responses.
+ */
+export function isRedirectEndpoint(op: Operation, resolvedOp?: ResolvedOperation): boolean {
+  if ((resolvedOp as any)?.urlBuilder) return true;
+  if ((op as any).successResponses?.some((r: any) => r.statusCode >= 300 && r.statusCode < 400)) return true;
+  if (
+    op.httpMethod === 'get' &&
+    op.response.kind === 'primitive' &&
+    (op.response as any).type === 'unknown' &&
+    op.queryParams.length > 0
+  ) {
+    return true;
+  }
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Mutually-exclusive parameter group support
+// ---------------------------------------------------------------------------
+
+/** PHP class name for a parameter group variant (e.g. ParentResourceById). */
+function groupVariantClassName(groupName: string, variantName: string): string {
+  return `${className(groupName)}${className(variantName)}`;
+}
+
+/**
+ * Derive a short PHP property name for a parameter within a variant class.
+ * Strips the group name prefix when present to avoid stuttering
+ * (e.g. parent_resource_id in group parent_resource -> id -> camelCase).
+ */
+export function deriveVariantFieldName(paramName: string, groupName: string): string {
+  const prefix = groupName + '_';
+  const stripped = paramName.startsWith(prefix) ? paramName.slice(prefix.length) : paramName;
+  return fieldName(stripped);
+}
+
+/**
+ * Generate PHP variant class files for all parameter groups on an operation.
+ * Each variant becomes a simple PHP class with readonly constructor properties.
+ */
+function generateParameterGroupFiles(
+  op: Operation,
+  ctx: EmitterContext,
+  modelMap: Map<string, Model>,
+): GeneratedFile[] {
+  const files: GeneratedFile[] = [];
+  const bodyFieldTypes = collectBodyFieldTypes(op, [...modelMap.values()]);
+
+  for (const group of op.parameterGroups ?? []) {
+    for (const variant of group.variants) {
+      const variantClass = groupVariantClassName(group.name, variant.name);
+      const lines: string[] = [];
+
+      lines.push(`namespace ${ctx.namespacePascal}\\Service;`);
+      lines.push('');
+      lines.push(`class ${variantClass}`);
+      lines.push('{');
+      lines.push('    public function __construct(');
+      for (let i = 0; i < variant.parameters.length; i++) {
+        const param = variant.parameters[i];
+        const effectiveType = bodyFieldTypes.get(param.name) ?? param.type;
+        const phpType = mapTypeRef(effectiveType, { qualified: true });
+        const phpName = deriveVariantFieldName(param.name, group.name);
+        const comma = ',';
+        lines.push(`        public readonly ${phpType} $${phpName}${comma}`);
+      }
+      lines.push('    ) {');
+      lines.push('    }');
+      lines.push('}');
+
+      files.push({
+        path: `lib/Service/${variantClass}.php`,
+        content: lines.join('\n'),
+        overwriteExisting: true,
+      });
+    }
   }
 
   return files;
 }
 
+/**
+ * Generate instanceof dispatch lines to serialize a grouped parameter
+ * into a target array ($query or $body) using each variant's wire names.
+ */
+function generateGroupDispatch(op: Operation, indent: string, target: '$query' | '$body' = '$query'): string[] {
+  const lines: string[] = [];
+
+  for (const group of op.parameterGroups ?? []) {
+    const phpParamName = fieldName(group.name);
+
+    for (let vi = 0; vi < group.variants.length; vi++) {
+      const variant = group.variants[vi];
+      const variantClass = groupVariantClassName(group.name, variant.name);
+      const keyword = vi === 0 ? 'if' : 'elseif';
+
+      lines.push(`${indent}${keyword} ($${phpParamName} instanceof ${variantClass}) {`);
+
+      for (const param of variant.parameters) {
+        const phpField = deriveVariantFieldName(param.name, group.name);
+        lines.push(`${indent}    ${target}['${param.name}'] = $${phpParamName}->${phpField};`);
+      }
+
+      lines.push(`${indent}}`);
+    }
+  }
+
+  return lines;
+}
+
 function generateMethod(
   lines: string[],
   op: Operation,
@@ -112,8 +240,9 @@ function generateMethod(
     ...getOpInferFromClient(resolvedOp),
   ]);
 
+  const isRedirect = isRedirectEndpoint(op, resolvedOp);
   const params = buildMethodParams(op, plan, modelMap, ctx, hiddenParams);
-  const returnType = getReturnType(plan, ctx);
+  const returnType = isRedirect ? 'string' : getReturnType(plan, ctx);
 
   // PHPDoc block
   const docParts: string[] = [];
@@ -150,14 +279,29 @@ function generateMethod(
     }
   }
 
-  // @param for query params
+  // @param for parameter groups (union-typed)
+  const groupedParamNames = collectGroupedParamNames(op);
+  for (const group of op.parameterGroups ?? []) {
+    const phpName = fieldName(group.name);
+    if (seenDocParams.has(phpName)) continue;
+    seenDocParams.add(phpName);
+    const variantTypes = group.variants.map((v) => groupVariantClassName(group.name, v.name));
+    const unionDocType = variantTypes.join('|');
+    const nullPrefix = group.optional ? 'null|' : '';
+    docParts.push(`@param ${nullPrefix}${unionDocType} $${phpName}`);
+  }
+
+  // @param for query params (skip grouped params — they appear as group union params)
   for (const q of op.queryParams) {
     if (hiddenParams.has(q.name)) continue;
+    if (groupedParamNames.has(q.name)) continue;
     const docType = mapTypeRefForPHPDoc(q.type);
     const phpName = fieldName(q.name);
     if (seenDocParams.has(phpName)) continue;
     seenDocParams.add(phpName);
-    const nullSuffix = !q.required && !docType.endsWith('|null') ? '|null' : '';
+    // order params with enum defaults are non-nullable (they default to Desc, not null)
+    const isNonNullableOrder = q.name === 'order' && q.type.kind === 'enum';
+    const nullSuffix = !q.required && !isNonNullableOrder && !docType.endsWith('|null') ? '|null' : '';
     const prefix = q.deprecated ? '(deprecated) ' : '';
     let desc = q.description ? ` ${prefix}${q.description}` : q.deprecated ? ' (deprecated)' : '';
     if (q.default != null) desc += ` Defaults to ${JSON.stringify(q.default)}.`;
@@ -183,6 +327,16 @@ function generateMethod(
     docParts.push(`@return ${returnType}`);
   }
 
+  // @throws — scope to what the method actually calls
+  if (!isRedirect) {
+    // HTTP methods can throw any WorkOSException (config, transport, API response)
+    docParts.push(`@throws \\${ctx.namespacePascal}\\Exception\\WorkOSException`);
+  } else if (getOpInferFromClient(resolvedOp).length > 0) {
+    // Redirect endpoints that inject client fields can throw ConfigurationException
+    docParts.push(`@throws \\${ctx.namespacePascal}\\Exception\\ConfigurationException`);
+  }
+  // Redirect endpoints with no inferFromClient: buildUrl() is pure, no @throws
+
   if (op.deprecated) docParts.push('@deprecated');
   lines.push(...phpDocComment(docParts.join('\n'), 4));
 
@@ -198,19 +352,69 @@ function generateMethod(
   const httpMethod = op.httpMethod.toUpperCase();
   const path = buildPathString(op);
 
-  if (plan.isPaginated) {
-    const queryLines = buildQueryArray(op);
-    if (queryLines.length > 0) {
-      lines.push('        $query = array_filter([');
+  if (isRedirect) {
+    // Redirect endpoint: construct URL client-side instead of making HTTP request
+    const queryLines = buildQueryArray(op, hiddenParams);
+    const hasDefaults = Object.keys(getOpDefaults(resolvedOp)).length > 0;
+    const hasInferred = getOpInferFromClient(resolvedOp).length > 0;
+    const hasGroups = (op.parameterGroups?.length ?? 0) > 0;
+    const needsQuery = queryLines.length > 0 || hasDefaults || hasInferred || hasGroups;
+
+    if (needsQuery) {
+      const groupedParams = collectGroupedParamNames(op);
+      const hasOptionalQuery = op.queryParams.some(
+        (q) => !q.required && !hiddenParams.has(q.name) && !groupedParams.has(q.name),
+      );
+      if (hasOptionalQuery) {
+        lines.push('        $query = array_filter([');
+      } else if (queryLines.length > 0) {
+        lines.push('        $query = [');
+      } else {
+        lines.push('        $query = [');
+      }
       for (const q of queryLines) {
         lines.push(`            ${q}`);
       }
-      lines.push('        ], fn ($v) => $v !== null);');
+      // Inject constant defaults
+      for (const [key, value] of Object.entries(getOpDefaults(resolvedOp))) {
+        lines.push(`            '${key}' => ${phpLiteral(value)},`);
+      }
+      if (hasOptionalQuery) {
+        lines.push('        ], fn ($v) => $v !== null);');
+      } else {
+        lines.push('        ];');
+      }
+      // Inject fields from client config
+      for (const clientField of getOpInferFromClient(resolvedOp)) {
+        lines.push(`        $query['${clientField}'] = ${clientFieldExpression(clientField)};`);
+      }
+      // Inject parameter group dispatch (instanceof checks)
+      lines.push(...generateGroupDispatch(op, '        '));
+      lines.push(`        return $this->client->buildUrl(path: ${path}, query: $query, options: $options);`);
+    } else {
+      lines.push(`        return $this->client->buildUrl(path: ${path}, query: [], options: $options);`);
+    }
+  } else if (plan.isPaginated) {
+    const queryLines = buildQueryArray(op);
+    const hasGroups = (op.parameterGroups?.length ?? 0) > 0;
+    const needsQuery = queryLines.length > 0 || hasGroups;
+    if (needsQuery) {
+      if (queryLines.length > 0) {
+        lines.push('        $query = array_filter([');
+        for (const q of queryLines) {
+          lines.push(`            ${q}`);
+        }
+        lines.push('        ], fn ($v) => $v !== null);');
+      } else {
+        lines.push('        $query = [];');
+      }
+      // Inject parameter group dispatch (instanceof checks)
+      lines.push(...generateGroupDispatch(op, '        '));
     }
     lines.push('        return $this->client->requestPage(');
     lines.push(`            method: '${httpMethod}',`);
     lines.push(`            path: ${path},`);
-    if (queryLines.length > 0) {
+    if (needsQuery) {
       lines.push('            query: $query,');
     }
     const itemType = op.pagination?.itemType;
@@ -260,6 +464,10 @@ function generateMethod(
       for (const clientField of getOpInferFromClient(resolvedOp)) {
         lines.push(`        $body['${clientField}'] = ${clientFieldExpression(clientField)};`);
       }
+      // Inject parameter group dispatch into body
+      if ((op.parameterGroups?.length ?? 0) > 0) {
+        lines.push(...generateGroupDispatch(op, '        ', '$body'));
+      }
     }
     // Build query params if present
     const deleteQueryLines = buildQueryArray(op);
@@ -311,6 +519,11 @@ function generateMethod(
     for (const clientField of getOpInferFromClient(resolvedOp)) {
       lines.push(`        $body['${clientField}'] = ${clientFieldExpression(clientField)};`);
     }
+    // Inject parameter group dispatch into body so sensitive fields
+    // (passwords, role slugs) never leak into the URL query string.
+    if ((op.parameterGroups?.length ?? 0) > 0) {
+      lines.push(...generateGroupDispatch(op, '        ', '$body'));
+    }
     lines.push('        $response = $this->client->request(');
     lines.push(`            method: '${httpMethod}',`);
     lines.push(`            path: ${path},`);
@@ -332,12 +545,18 @@ function generateMethod(
     const queryLines = buildQueryArray(op, hiddenParams);
     const hasDefaults = Object.keys(getOpDefaults(resolvedOp)).length > 0;
     const hasInferred = getOpInferFromClient(resolvedOp).length > 0;
-    const needsQuery = queryLines.length > 0 || hasDefaults || hasInferred;
+    const hasGroups = (op.parameterGroups?.length ?? 0) > 0;
+    const needsQuery = queryLines.length > 0 || hasDefaults || hasInferred || hasGroups;
 
     if (needsQuery) {
-      const hasOptionalQuery = op.queryParams.some((q) => !q.required && !hiddenParams.has(q.name));
+      const groupedParams = collectGroupedParamNames(op);
+      const hasOptionalQuery = op.queryParams.some(
+        (q) => !q.required && !hiddenParams.has(q.name) && !groupedParams.has(q.name),
+      );
       if (hasOptionalQuery) {
         lines.push('        $query = array_filter([');
+      } else if (queryLines.length > 0) {
+        lines.push('        $query = [');
       } else {
         lines.push('        $query = [');
       }
@@ -357,6 +576,8 @@ function generateMethod(
       for (const clientField of getOpInferFromClient(resolvedOp)) {
         lines.push(`        $query['${clientField}'] = ${clientFieldExpression(clientField)};`);
       }
+      // Inject parameter group dispatch (instanceof checks)
+      lines.push(...generateGroupDispatch(op, '        '));
     }
     lines.push('        $response = $this->client->request(');
     lines.push(`            method: '${httpMethod}',`);
@@ -395,6 +616,7 @@ function buildMethodParams(
   const optional: string[] = [];
   const usedNames = new Set<string>();
   const hidden = hiddenParams ?? new Set();
+  const groupedParams = collectGroupedParamNames(op);
 
   // Path params (always required)
   for (const p of op.pathParams) {
@@ -429,15 +651,41 @@ function buildMethodParams(
     }
   }
 
-  // Query params
+  // Parameter group union-typed params (before individual query params)
+  for (const group of op.parameterGroups ?? []) {
+    const phpName = fieldName(group.name);
+    if (usedNames.has(phpName)) continue;
+    usedNames.add(phpName);
+    // PHP 8.0+ union syntax: VariantA|VariantB $paramName
+    const variantTypes = group.variants.map((v) => groupVariantClassName(group.name, v.name));
+    const unionType = variantTypes.join('|');
+    if (group.optional) {
+      optional.push(`null|${unionType} $${phpName} = null`);
+    } else {
+      required.push(`${unionType} $${phpName}`);
+    }
+  }
+
+  // Query params (skip grouped params — they are serialized via group dispatch)
   for (const q of op.queryParams) {
     if (hidden.has(q.name)) continue;
+    if (groupedParams.has(q.name)) continue;
     const phpType = mapTypeRef(q.type, { qualified: true });
     let phpName = fieldName(q.name);
     if (usedNames.has(phpName)) continue;
     usedNames.add(phpName);
     if (q.required) {
       required.push(`${phpType} $${phpName}`);
+    } else if (q.name === 'order') {
+      // Hardcode order default to desc for pagination consistency
+      if (q.type.kind === 'enum') {
+        const enumType = mapTypeRef(q.type, { qualified: true });
+        const caseName = toPascalCase('desc');
+        optional.push(`${enumType} $${phpName} = ${enumType}::${caseName}`);
+      } else {
+        const nullableType = phpType.startsWith('?') ? phpType : `?${phpType}`;
+        optional.push(`${nullableType} $${phpName} = 'desc'`);
+      }
     } else {
       const nullableType = phpType.startsWith('?') ? phpType : `?${phpType}`;
       optional.push(`${nullableType} $${phpName} = null`);
@@ -504,12 +752,15 @@ function isEnumType(ref: import('@workos/oagen').TypeRef): boolean {
 
 function buildQueryArray(op: Operation, hiddenParams?: Set<string>): string[] {
   const hidden = hiddenParams ?? new Set();
+  const groupedParams = collectGroupedParamNames(op);
   return op.queryParams
-    .filter((q) => !hidden.has(q.name))
+    .filter((q) => !hidden.has(q.name) && !groupedParams.has(q.name))
     .map((q) => {
       const phpName = fieldName(q.name);
       if (isEnumType(q.type)) {
-        const nullsafe = q.required ? '' : '?';
+        // order params with enum defaults are non-nullable (default to Desc, not null)
+        const isNonNullableOrder = q.name === 'order' && q.type.kind === 'enum';
+        const nullsafe = q.required || isNonNullableOrder ? '' : '?';
         return `'${q.name}' => $${phpName}${nullsafe}->value,`;
       }
       return `'${q.name}' => $${phpName},`;
@@ -534,13 +785,18 @@ function clientFieldExpression(field: string): string {
   }
 }
 
-function collectImports(service: Service, ctx: EmitterContext): string[] {
+function collectImports(
+  service: Service,
+  ctx: EmitterContext,
+  resolvedLookup?: Map<string, ResolvedOperation>,
+): string[] {
   const imports = new Set<string>();
   const ns = ctx.namespacePascal;
 
   for (const op of service.operations) {
     const plan = planOperation(op);
-    if (plan.responseModelName && !plan.isPaginated) {
+    const resolved = resolvedLookup ? lookupResolved(op, resolvedLookup) : undefined;
+    if (plan.responseModelName && !plan.isPaginated && !isRedirectEndpoint(op, resolved)) {
       imports.add(`${ns}\\Resource\\${className(plan.responseModelName)}`);
     }
     if (op.pagination?.itemType.kind === 'model') {

package/src/php/tests.ts

@@ -7,12 +7,20 @@ import type {
   Model,
   ResolvedOperation,
 } from '@workos/oagen';
-import { planOperation, toCamelCase } from '@workos/oagen';
+import { planOperation, toCamelCase, toPascalCase } from '@workos/oagen';
 import { className, enumClassName, resolveMethodName, snakeName, servicePropertyName } from './naming.js';
 import { isListWrapperModel } from './models.js';
 import { generateFixtures } from './fixtures.js';
-import { getMountTarget, groupByMount, buildHiddenParams } from '../shared/resolved-ops.js';
+import {
+  getMountTarget,
+  groupByMount,
+  buildHiddenParams,
+  getOpDefaults,
+  getOpInferFromClient,
+  collectGroupedParamNames,
+} from '../shared/resolved-ops.js';
 import { resolveWrapperParams } from '../shared/wrapper-utils.js';
+import { isRedirectEndpoint, deriveVariantFieldName } from './resources.js';
 
 /**
  * Generate PHPUnit test files and fixture JSON files.
@@ -20,16 +28,6 @@ import { resolveWrapperParams } from '../shared/wrapper-utils.js';
 export function generateTests(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
   const files: GeneratedFile[] = [];
 
-  // Generate fixture JSON files
-  const fixtures = generateFixtures(spec);
-  for (const fixture of fixtures) {
-    files.push({
-      path: fixture.path,
-      content: fixture.content,
-      headerPlacement: 'skip',
-    });
-  }
-
   // TestHelper is now hand-maintained in the target SDK (@oagen-ignore-file).
 
   // Collect all operations per mount target using resolved per-operation mounts.
@@ -72,6 +70,16 @@ export function generateTests(spec: ApiSpec, ctx: EmitterContext): GeneratedFile
     overwriteExisting: true,
   });
 
+  // Generate fixture JSON files
+  const fixtures = generateFixtures(spec);
+  for (const fixture of fixtures) {
+    files.push({
+      path: fixture.path,
+      content: fixture.content,
+      headerPlacement: 'skip',
+    });
+  }
+
   return files;
 }
 
@@ -146,6 +154,17 @@ function generateMountGroupTest(
       lines.push(`        $this->assertStringEndsWith('${expectedPath}', $request->getUri()->getPath());`);
       // Query string serialization assertions
       emitQueryAssertions(lines, op, ctx, hidden);
+    } else if (isRedirectEndpoint(op, resolvedOp)) {
+      // Redirect endpoint: URL is built locally, no HTTP request made.
+      // Pass all params (including optional) to verify they appear in the URL.
+      lines.push('        $client = $this->createMockClient([]);');
+      lines.push(
+        `        $result = $client->${accessor}()->${method}(${buildTestArgs(op, ctx, { includeOptional: true, hidden })});`,
+      );
+      lines.push('        $this->assertIsString($result);');
+      lines.push(`        $this->assertStringContainsString('${expectedPath}', $result);`);
+      // Query param assertions for the generated URL
+      emitRedirectQueryAssertions(lines, op, ctx, hidden, resolvedOp);
     } else if (plan.responseModelName) {
       const modelName = className(plan.responseModelName);
       const fixtureName = `${snakeName(plan.responseModelName)}`;
@@ -329,9 +348,23 @@ function buildTestArgs(
     }
   }
 
-  // Query params
+  // Parameter group args (union-typed) — emit first variant constructor
+  const groupedParamNames = collectGroupedParamNames(op);
+  for (const group of op.parameterGroups ?? []) {
+    if (!group.optional || includeOptional) {
+      const variant = group.variants[0];
+      const variantClass = `${className(group.name)}${className(variant.name)}`;
+      const variantArgs = variant.parameters
+        .map((p) => `${deriveVariantFieldName(p.name, group.name)}: 'test_value'`)
+        .join(', ');
+      args.push(`${toCamelCase(group.name)}: new \\${ctx.namespacePascal}\\Service\\${variantClass}(${variantArgs})`);
+    }
+  }
+
+  // Query params (skip grouped params — they're handled above)
   for (const q of op.queryParams) {
     if (hidden.has(q.name)) continue;
+    if (groupedParamNames.has(q.name)) continue;
     if (!q.required && !includeOptional) continue;
     const phpName = toCamelCase(q.name);
     if (usedNames.has(phpName)) continue;
@@ -363,11 +396,8 @@ function generateTestValue(ref: { kind: string; type?: string; name?: string },
         const e = ctx.spec.enums.find((en) => en.name === ref.name);
         if (e && e.values.length > 0) {
           const enumClass = enumClassName(ref.name);
-          const caseName = String(e.values[0].name)
-            .split(/[_\s-]+/)
-            .filter(Boolean)
-            .map((p) => p.charAt(0).toUpperCase() + p.slice(1).toLowerCase())
-            .join('');
+          // Must match the case-name logic in enums.ts
+          const caseName = toPascalCase(String(e.values[0].name).toLowerCase());
           return `\\WorkOS\\Resource\\${enumClass}::${caseName}`;
         }
       }
@@ -375,6 +405,13 @@ function generateTestValue(ref: { kind: string; type?: string; name?: string },
     }
     case 'array':
       return '[]';
+    case 'map':
+      return '[]';
+    case 'nullable':
+      return generateTestValue(
+        (ref as unknown as { inner: { kind: string; type?: string; name?: string } }).inner,
+        ctx,
+      );
     case 'model': {
       if (ref.name) {
         const modelClass = className(ref.name);
@@ -471,9 +508,18 @@ function emitFieldHydrationAssertions(
  */
 function emitQueryAssertions(lines: string[], op: Operation, ctx: EmitterContext, hidden?: Set<string>): void {
   if (op.queryParams.length === 0) return;
+  const groupedParams = collectGroupedParamNames(op);
   lines.push('        parse_str($request->getUri()->getQuery(), $query);');
+  // Assert first variant's params from parameter groups
+  for (const group of op.parameterGroups ?? []) {
+    const variant = group.variants[0];
+    for (const param of variant.parameters) {
+      lines.push(`        $this->assertSame('test_value', $query['${param.name}']);`);
+    }
+  }
   for (const q of op.queryParams) {
     if (hidden?.has(q.name)) continue;
+    if (groupedParams.has(q.name)) continue;
     const innerType =
       q.type.kind === 'nullable' ? (q.type as { inner: { kind: string; type?: string; name?: string } }).inner : q.type;
     if (innerType.kind === 'enum' && innerType.name) {
@@ -499,6 +545,60 @@ function emitQueryAssertions(lines: string[], op: Operation, ctx: EmitterContext
   }
 }
 
+/**
+ * Emit query param assertions for redirect endpoint URLs.
+ * Parses the query string from the built URL and asserts visible params,
+ * hidden defaults (e.g., response_type), and inferred client fields (e.g., client_id).
+ */
+function emitRedirectQueryAssertions(
+  lines: string[],
+  op: Operation,
+  ctx: EmitterContext,
+  hidden: Set<string>,
+  resolvedOp?: ResolvedOperation,
+): void {
+  const hasVisibleQueryParams = op.queryParams.some((q) => !hidden.has(q.name));
+  const defaults = getOpDefaults(resolvedOp);
+  const inferred = getOpInferFromClient(resolvedOp);
+  if (!hasVisibleQueryParams && Object.keys(defaults).length === 0 && inferred.length === 0) return;
+
+  lines.push("        parse_str(parse_url($result, PHP_URL_QUERY) ?? '', $query);");
+
+  // Assert visible query params (same logic as emitQueryAssertions but reading from $query parsed from URL)
+  for (const q of op.queryParams) {
+    if (hidden.has(q.name)) continue;
+    const innerType =
+      q.type.kind === 'nullable' ? (q.type as { inner: { kind: string; type?: string; name?: string } }).inner : q.type;
+    if (innerType.kind === 'enum' && innerType.name) {
+      const e = ctx.spec.enums.find((en) => en.name === innerType.name);
+      if (e && e.values.length > 0) {
+        lines.push(`        $this->assertSame('${e.values[0].value}', $query['${q.name}']);`);
+      }
+    } else if (innerType.kind === 'primitive') {
+      switch (innerType.type) {
+        case 'string':
+          lines.push(`        $this->assertSame('test_value', $query['${q.name}']);`);
+          break;
+        case 'integer':
+        case 'number':
+        case 'boolean':
+          lines.push(`        $this->assertArrayHasKey('${q.name}', $query);`);
+          break;
+      }
+    }
+  }
+
+  // Assert hidden defaults (e.g., response_type => 'code')
+  for (const [key, value] of Object.entries(defaults)) {
+    lines.push(`        $this->assertSame('${value}', $query['${key}']);`);
+  }
+
+  // Assert inferred client fields are present (e.g., client_id)
+  for (const key of inferred) {
+    lines.push(`        $this->assertArrayHasKey('${key}', $query);`);
+  }
+}
+
 /**
  * Emit body field assertions for POST/PUT/PATCH operations.
  * Only asserts primitive required fields (strings, numbers, booleans).

package/src/php/type-map.ts

@@ -15,7 +15,14 @@ export function mapTypeRef(ref: TypeRef, opts?: { qualified?: boolean }): string
     enum: (r) => `${prefix}${enumClassName(r.name)}`,
     union: (r, variants) => joinUnionVariants(r, variants),
     nullable: (_ref, inner) => `?${inner}`,
-    literal: (r) => (typeof r.value === 'number' ? (Number.isInteger(r.value) ? 'int' : 'float') : 'string'),
+    literal: (r) =>
+      typeof r.value === 'number'
+        ? Number.isInteger(r.value)
+          ? 'int'
+          : 'float'
+        : typeof r.value === 'boolean'
+          ? 'bool'
+          : 'string',
     map: (_ref, _value) => 'array',
   });
 }
@@ -34,7 +41,14 @@ export function mapTypeRefForPHPDoc(ref: TypeRef, opts?: { prefix?: string }): s
     enum: (r) => `${prefix}${enumClassName(r.name)}`,
     union: (r, variants) => joinDocUnionVariants(r, variants),
     nullable: (_ref, inner) => `${inner}|null`,
-    literal: (r) => (typeof r.value === 'string' ? 'string' : typeof r.value === 'number' ? 'int' : 'string'),
+    literal: (r) =>
+      typeof r.value === 'string'
+        ? 'string'
+        : typeof r.value === 'number'
+          ? 'int'
+          : typeof r.value === 'boolean'
+            ? 'bool'
+            : 'string',
     map: (_ref, value) => `array<string, ${value}>`,
   });
 }