Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

[QueryParameter] Support PHP backed enums in OpenAPI schemas

Open
  • Is something wrong?
#8,686 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
35/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
php
Domain
api

Research direction

Start with how QueryParameter schemas are turned into OpenAPI output and how query values are validated, since the payload names neither file nor test. Check whether the existing enum handling for resource properties can be reused for a QueryParameter schema that names an enum class. The syntax is still open (a 'enumClass' key inside schema, or a dedicated option), so agree on it with maintainers first. Done means the generated schema lists the backed enum's values and incoming values are validated against them.

Written by the indexing model from the issue text.

Description

Description

In API Platform 4.4 / 5.0, defining a QueryParameter with allowed values from a PHP backed enum requires manually duplicating its values in the OpenAPI schema.

For example:

enum FooEnum: string
{
    case A = 'a';
    case B = 'b';
    case C = 'c';
}

Currently, the values must be explicitly listed:

new QueryParameter(
    schema: [
        'type' => 'string',
        'enum' => ['a', 'b', 'c'],
    ],
)

This duplicates the enum definition and requires updating the schema whenever enum cases change.

PHP does not allow calling FooEnum::cases() directly in attribute arguments.

Proposed solution

Allow referencing a PHP backed enum class directly in a QueryParameter schema.

For example:

new QueryParameter(
    schema: [
        'type' => 'string',
        'enumClass' => FooEnum::class,
    ],
)

Alternatively, a dedicated enumClass option on QueryParameter could be introduced.

The syntax is illustrative; the goal is to avoid manually duplicating enum values.

Expected behavior

API Platform should automatically:

  • Extract backed enum values using FooEnum::cases().
  • Include these values in the generated OpenAPI schema.
  • Validate incoming parameter values against the enum.

Generated OpenAPI schema:

type: string
enum:
  - a
  - b
  - c

Automatic conversion to PHP enum instances is not required as part of this feature.

Additional context

API Platform already supports PHP backed enums in resource properties and OpenAPI schema generation.

It would be useful to provide equivalent support for explicitly declared query parameters, keeping the enum as the single source of truth.

Dominant language
PHP
Stars
2.6k
Forks
989
Avg merge
1d 23h
Merged PRs (30d)
102

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from api-platform/core

All issues in api-platform/core

Similar issues

More PHP issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.