Skip to content

feat(metadata): enumClass on parameters - #8858

Open
valentingoulier wants to merge 3 commits into
api-platform:mainfrom
valentingoulier:feat/parameter-enum-class
Open

valentingoulier wants to merge 3 commits into
api-platform:mainfrom
valentingoulier:feat/parameter-enum-class

Conversation

@valentingoulier

@valentingoulier valentingoulier commented Nov 16, 2026 •

Copy link
Copy Markdown
Q A
Branch? main
Tickets Closes #8686, closes #8816
License MIT
Doc PR to do once the syntax is agreed

A parameter can name a PHP backed enum as the source of its allowed values, instead of repeating them in schema['enum']:

'status' => new QueryParameter(enumClass: Status::class),

The enum fills the schema type (string or integer, from the backing type) and enum. OpenAPI and the parameter validation already read these keys.

It also answers #8816: BackedEnumFilter is deprecated in favour of ExactFilter, which does not document the enum values, and an attribute cannot call array_column(TypeEnum::cases(), 'value'). With this PR:

'type' => new QueryParameter(filter: new ExactFilter(), property: 'type', enumClass: TypeEnum::class),

documents the enum on both type and type[], and rejects other values with a 422.

Functional tests:

  • tests/Functional/Parameters/EnumClassParameterTest.php: without a filter (valid value accepted, invalid value gives a 422, type + enum in the OpenAPI document). Resource in tests/Fixtures/TestBundle/ApiResource/EnumClassParameter/.
  • tests/Functional/Parameters/EnumClassExactFilterTest.php: with ExactFilter, Doctrine ORM and MongoDB ODM (single value and list of values, string and int backed enums, 422 outside the enum, OpenAPI schema of both forms). Fixtures in tests/Fixtures/TestBundle/Entity/Issue8816/ and tests/Fixtures/TestBundle/Document/Issue8816/.
  • tests/Functional/GraphQl/EnumClassParameterTest.php: the same resource as a GraphQL collection (argument types, filtering on a value).
  • src/Laravel/Tests/EnumClassParameterTest.php: without a filter in the Laravel workbench (valid value, 422, OpenAPI schema).

Unit tests:

  • ParameterResourceMetadataCollectionFactoryTest (--filter EnumClass): schema resolution, and the shape of the parameter depending on the filter, castToArray, schema['type'] and nativeType.
  • ParameterValidationConstraintsTest::testScalarTypeAppliesToEachValueOfAList.

Behaviour worth a look:

  • A type or enum key written in schema wins over the one derived from the enum.
  • An int-backed enum sets castToNativeType to true unless it is explicitly false: the value arrives as a string and Choice is strict.
  • The enum is resolved before the filter metadata, so it behaves like a hand-written schema: a schema provided by the filter is not merged.
  • A class that is not a backed enum throws an InvalidArgumentException when the metadata is built.
  • With a filter, the parameter keeps the "value or list of values" shape a filtered parameter has without an enum (?type=a and ?type[]=a&type[]=b), unless castToArray is false, a nativeType is set or schema['type'] is written. Without a filter, it stays a single value.
  • ParameterValidationConstraints: the scalar Type constraint (integer, boolean, number with castToNativeType) is now part of the per-value constraints, so it applies to each value of a list instead of the list itself. Without this, ?level[]=1&level[]=3 was rejected for an int-backed enum.

Not covered:

  • Inferring the enum from the type of the filtered property, as ExactFilter on enum typed property is not generating enums in docs.jsonopenapi #8816 first suggests. It cannot be done for every parameter with a property (an OrderFilter or a PartialSearchFilter on an enum property must not get the constraint), so the filter would have to opt in, and values accepted today would start giving a 422. I left it out; tell me if you want it and how the filter should declare it.
  • nativeType: Type::enum(...), which the BackedEnumFilter deprecation message mentions, does not fill the schema. It could become an alias of enumClass.
  • enum_class under api_platform.defaults.parameters is accepted but not resolved, and the YAML/XML extractors do not expose it (same as cast_to_native_type).
  • GraphQL: the argument is a String or an Int (not a GraphQL enum type) and takes a single value. A value outside the enum is not rejected there, it gives an empty collection: parameter constraints are only validated on HTTP requests, with or without enumClass.
  • Laravel: only tested without a filter.
  • No conversion to an enum instance, as [QueryParameter] Support PHP backed enums in OpenAPI schemas #8686 says.

#8816 was reported on 4.4; this targets main as a feature. Tell me if you would rather have a separate fix on 4.4.

I picked a dedicated argument over an enumClass key inside schema to keep the schema plain JSON Schema. Happy to change the syntax if you prefer another one. I have not added a CHANGELOG entry; tell me if you want one.

🤖 Generated with Claude Code

Copilot AI balanced review requested due to automatic review settings November 16, 2026 22:25
A parameter can name a PHP backed enum as the source of its allowed
values. The enum fills the schema "type" and "enum", which OpenAPI and
the parameter validation already read.

Closes api-platform#8686

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@valentingoulier
valentingoulier force-pushed the feat/parameter-enum-class branch from d4b8207 to 65c1303 Compare November 16, 2026 22:26

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

The enum-backed parameter metadata change has no active review issues blocking approval.

No open issues 🎉

What changed in this PR

Adds enumClass to parameter metadata, addressing #8686 by letting query and header parameters derive allowed values from PHP backed enums for existing OpenAPI generation and validation.

Changes:

  • Adds the enumClass constructor option and immutable accessor methods.
  • Resolves enum values and backing types into schemas, preserves explicit schema keys, and enables integer casting unless disabled.
  • Adds unit and functional coverage for schema generation, validation, overrides, and invalid enum classes.
File Description
tests/​Functional/​Parameters/​EnumClassParameterTest.php Tests accepted values, rejected values, and OpenAPI schemas.
tests/​Fixtures/​TestBundle/​ApiResource/​EnumClassParameter/​Status.php Adds a string-backed enum for functional tests.
tests/​Fixtures/​TestBundle/​ApiResource/​EnumClassParameter/​Priority.php Adds an integer-backed enum for functional tests.
tests/​Fixtures/​TestBundle/​ApiResource/​EnumClassParameter/​EnumClassParameter.php Adds an isolated resource with enum-backed query parameters.
src/​Metadata/​Tests/​Resource/​Factory/​ParameterResourceMetadataCollectionFactoryTest.php Tests enum resolution, casting, schema precedence, and invalid classes.
src/​Metadata/​Tests/​Fixtures/​Enum/​UnitSuit.php Supplies an unsupported unit enum for rejection tests.
src/​Metadata/​Tests/​Fixtures/​Enum/​StringBackedStatus.php Supplies string enum values for metadata tests.
src/​Metadata/​Tests/​Fixtures/​Enum/​IntBackedPriority.php Supplies integer enum values for metadata tests.
src/​Metadata/​Tests/​Fixtures/​ApiResource/​WithEnumParameter.php Defines query and header parameter configurations for unit tests.
src/​Metadata/​Resource/​Factory/​ParameterResourceMetadataCollectionFactory.php Resolves backed enums into schemas before filter defaults.
src/​Metadata/​Parameter.php Exposes the enumClass option, getter, and immutable setter.

Review effort: Balanced

valentingoulier and others added 2 commits November 17, 2026 09:57
A filter such as ExactFilter takes a value or a list of values. With
"enumClass", the scalar schema type narrowed the parameter to a single
value, so "?type[]=a&type[]=b" was rejected while still documented.

The enum now constrains the values a filter receives, not their shape.
The scalar type constraint is applied to each value of a list.

Closes api-platform#8816

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Unit tests for the shape of an enumClass parameter (value or list of
values with a filter) and for the scalar type constraint applied to
each value of a list.

The ExactFilter functional test now runs with the MongoDB ODM, and
enumClass is tested as a GraphQL collection argument and in the Laravel
workbench.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

ExactFilter on enum typed property is not generating enums in docs.jsonopenapi [QueryParameter] Support PHP backed enums in OpenAPI schemas

2 participants