fix(php): honor OpenAPI default beside $ref in toDefaultValue

modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/AbstractPhpCodegen.java

@@ -636,6 +636,17 @@ public String toDefaultValue(Schema p) {
             }
         }
 
+        // OAS 3.x: `default` may appear alongside `$ref` on the same schema (e.g. optional query param whose schema
+        // references an enum model). That wrapper is often not classified as string/number here, but still carries
+        // the default OpenAPI value — needed so Mustache can emit `query->get(..., <default>)` for php-symfony.
+        if (p.getDefault() != null) {
+            Object def = p.getDefault();
+            if (def instanceof String) {
+                return "'" + escapeTextInSingleQuotes((String) def) + "'";
+            }
+            return def.toString();
+        }
+
         return null;
     }
 

modules/openapi-generator/src/test/java/org/openapitools/codegen/php/PhpSymfonyServerCodegenTest.java

@@ -216,12 +216,14 @@ public void testPetstoreDottedEnumRefQueryParameterUsesShortClassInApiInterface(
         Assert.assertTrue(
                 apiContent.contains("use Org\\OpenAPITools\\Petstore\\Model\\PetModelPetStatus;"),
                 "Expected enum model import");
+        // Optional enum ref may carry an OpenAPI default: php-symfony api.mustache omits leading "?" / "|null" when
+        // defaultValue is set (handler always receives the enum after the controller applies the default).
         Assert.assertTrue(
-                apiContent.contains("?PetModelPetStatus $status"),
+                Pattern.compile("public function listPets\\(\\s*\\??PetModelPetStatus\\s+\\$status,").matcher(apiContent).find(),
                 "Expected enum ref query param to use short class in type hint");
         Assert.assertTrue(
-                Pattern.compile("@param\\s+PetModelPetStatus\\|null\\s+\\$status\\b").matcher(apiContent).find(),
-                "PHPDoc @param should use short PetModelPetStatus|null (consistent with use import)");
+                Pattern.compile("@param\\s+PetModelPetStatus(\\|null)?\\s+\\$status\\b").matcher(apiContent).find(),
+                "PHPDoc @param should use short PetModelPetStatus (optional |null when no default in spec)");
         Assert.assertFalse(
                 apiContent.contains("?\\Org\\OpenAPITools\\Petstore\\Model\\PetModelPetStatus $status"),
                 "Signature must not use leading-backslash FQCN when a matching use import exists");
@@ -234,6 +236,73 @@ public void testPetstoreDottedEnumRefQueryParameterUsesShortClassInApiInterface(
         output.deleteOnExit();
     }
 
+    /**
+     * Optional {@code in: query} parameter: {@code required: false}, schema is an enum {@code $ref} with a valid
+     * {@code default} (see OpenAPI 3.x). Omitting the query key must be equivalent to sending that default; the
+     * generated controller must not reject the request in validation solely because the value was absent.
+     * <p>
+     * Spec: {@code src/test/resources/3_1/php-symfony/optional-enum-query-ref-default.yaml}. Product doc:
+     * {@code php-symfony.md} section &quot;可选 query：带默认值的非必填枚举 {@code $ref} 缺省却仍被拒绝&quot;.
+     * <p>
+     * Expected generated behavior (any one is acceptable):
+     * <ul>
+     *   <li>Pass the OpenAPI default into {@code Request::query->get} for {@code tone}, and/or</li>
+     *   <li>Apply the Elvis default line ({@code $tone = $tone?:...}) after the read (see {@code api_controller.mustache}), and/or</li>
+     *   <li>Wrap enum {@code Assert\\Type} in {@code Assert\\Optional} for non-required enum refs (see {@code api_input_validation.mustache}).</li>
+     * </ul>
+     * Also asserts the integer optional {@code limit} parameter still receives {@code get('limit', 10)} as a control.
+     * <p>
+     * <b>Note:</b> This test fails on the generator until optional enum-ref query parameters expose
+     * {@link org.openapitools.codegen.CodegenParameter#defaultValue} (or equivalent) so templates apply the OpenAPI
+     * default and/or skip strict {@code Assert\\Type} on {@code null}. It is intended to lock the fix described in the
+     * php-symfony troubleshooting doc.
+     */
+    @Test
+    public void testOptionalEnumRefQueryParameterWithDefaultAppliesOpenApiSemantics() throws Exception {
+        Map<String, Object> properties = new HashMap<>();
+        properties.put("invokerPackage", "Org\\OpenAPITools\\FeedHints");
+        properties.put(AbstractPhpCodegen.SRC_BASE_PATH, "src");
+
+        File output = Files.createTempDirectory("test").toFile();
+
+        final CodegenConfigurator configurator = new CodegenConfigurator()
+                .setGeneratorName("php-symfony")
+                .setAdditionalProperties(properties)
+                .setInputSpec("src/test/resources/3_1/php-symfony/optional-enum-query-ref-default.yaml")
+                .setOutputDir(output.getAbsolutePath().replace("\\", "/"));
+
+        final ClientOptInput clientOptInput = configurator.toClientOptInput();
+        DefaultGenerator generator = new DefaultGenerator();
+        List<File> files = generator.opts(clientOptInput).generate();
+
+        File controllerFile = files.stream()
+                .filter(f -> "DefaultController.php".equals(f.getName()) && f.getPath().contains("Controller" + File.separator))
+                .findFirst()
+                .orElseThrow(() -> new AssertionError("DefaultController.php not generated"));
+
+        String controller = Files.readString(controllerFile.toPath(), StandardCharsets.UTF_8);
+
+        Assert.assertTrue(
+                controller.contains("$request->query->get('limit', 10)"),
+                "Integer optional query with default should pass default as second argument to query->get (control case)");
+
+        boolean defaultInGet = Pattern.compile("\\$request->query->get\\('tone',\\s*").matcher(controller).find();
+        boolean elvisDefault = Pattern.compile("\\$tone\\s*=\\s*\\$tone\\?:").matcher(controller).find();
+        boolean optionalEnumTypeAssert =
+                controller.contains("new Assert\\Optional(")
+                        && controller.contains("PetAnnouncementTone");
+
+        Assert.assertTrue(
+                defaultInGet || elvisDefault || optionalEnumTypeAssert,
+                "Omitted optional enum-ref query with OpenAPI default must apply default (get/Elvis) and/or use "
+                        + "Assert\\Optional around enum Type so null is valid before default is applied; "
+                        + "see optional-enum-query-ref-default.yaml and php-symfony troubleshooting doc");
+
+        assertGeneratedPhpSyntaxValid(controllerFile);
+
+        output.deleteOnExit();
+    }
+
     /**
      * Runs {@code php -l} on the file. Skips if {@code php} is not available (optional toolchain).
      */

modules/openapi-generator/src/test/resources/3_1/php-symfony/optional-enum-query-ref-default.yaml

@@ -0,0 +1,42 @@
+# Minimal OpenAPI 3.1 spec: optional query with enum $ref + default (components.parameters).
+# Repro pattern: omitting the query key should behave like the declared default; php-symfony
+# may still validate null as enum type before business logic. See project troubleshooting doc.
+openapi: 3.1.0
+info:
+  title: Optional enum query ref with default (php-symfony repro)
+  version: '1.0'
+paths:
+  /pets/feed-hints:
+    get:
+      operationId: listFeedHints
+      parameters:
+        - $ref: '#/components/parameters/ToneQuery'
+        - name: limit
+          in: query
+          required: false
+          description: Integer optional query with default (often generated correctly).
+          schema:
+            type: integer
+            format: int32
+            default: 10
+            minimum: 1
+            maximum: 50
+      responses:
+        '200':
+          description: OK
+components:
+  parameters:
+    ToneQuery:
+      name: tone
+      in: query
+      required: false
+      description: Optional filter; default applies when the query key is omitted.
+      schema:
+        $ref: '#/components/schemas/PetAnnouncementTone'
+        default: friendly
+  schemas:
+    PetAnnouncementTone:
+      type: string
+      enum:
+        - friendly
+        - formal