Repository navigation
feat(metadata): enumClass on parameters - #8858
Open
valentingoulier wants to merge 3 commits into
Open
valentingoulier wants to merge 3 commits into
valentingoulier wants to merge 3 commits into
Conversation
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
force-pushed
the
feat/parameter-enum-class
branch
from
November 16, 2026 22:26
d4b8207 to
65c1303
Compare
Contributor
There was a problem hiding this comment.
🟢 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
enumClassconstructor 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
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
A parameter can name a PHP backed enum as the source of its allowed values, instead of repeating them in
schema['enum']:The enum fills the schema
type(stringorinteger, from the backing type) andenum. OpenAPI and the parameter validation already read these keys.It also answers #8816:
BackedEnumFilteris deprecated in favour ofExactFilter, which does not document the enum values, and an attribute cannot callarray_column(TypeEnum::cases(), 'value'). With this PR:documents the enum on both
typeandtype[], 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+enumin the OpenAPI document). Resource intests/Fixtures/TestBundle/ApiResource/EnumClassParameter/.tests/Functional/Parameters/EnumClassExactFilterTest.php: withExactFilter, 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 intests/Fixtures/TestBundle/Entity/Issue8816/andtests/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']andnativeType.ParameterValidationConstraintsTest::testScalarTypeAppliesToEachValueOfAList.Behaviour worth a look:
typeorenumkey written inschemawins over the one derived from the enum.castToNativeTypeto true unless it is explicitly false: the value arrives as a string andChoiceis strict.InvalidArgumentExceptionwhen the metadata is built.?type=aand?type[]=a&type[]=b), unlesscastToArrayis false, anativeTypeis set orschema['type']is written. Without a filter, it stays a single value.ParameterValidationConstraints: the scalarTypeconstraint (integer,boolean,numberwithcastToNativeType) 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[]=3was rejected for an int-backed enum.Not covered:
property(anOrderFilteror aPartialSearchFilteron 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 theBackedEnumFilterdeprecation message mentions, does not fill the schema. It could become an alias ofenumClass.enum_classunderapi_platform.defaults.parametersis accepted but not resolved, and the YAML/XML extractors do not expose it (same ascast_to_native_type).Stringor anInt(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 withoutenumClass.#8816 was reported on 4.4; this targets
mainas a feature. Tell me if you would rather have a separate fix on 4.4.I picked a dedicated argument over an
enumClasskey insideschemato 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