Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

[QueryParameter] Support PHP backed enums in OpenAPI schemas

Abierto
  • ¿Algo no está bien?
#8,686 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
4/5
Tiempo estimado
3-5 días
Aptitud para principiantes
35/100
Tipo de issue
Nueva funcionalidad
Claridad
Bastante claro
Estado de actividad
Activo
Stack tecnológico
php
Área
api

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.

Lenguaje dominante
PHP
Estrellas
2.6k
Forks
989
Merge medio
2 d 4 h
PR fusionados (30 d)
90

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de api-platform/core

Todos los issues de api-platform/core

Issues similares

Más issues de PHP

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.