Hacktoberfest 2026 : les issues que les mainteneurs ont marquées pour octobre, ouvertes et accessibles aux débutants. Parcourir les issues Hacktoberfest

[QueryParameter] Support PHP backed enums in OpenAPI schemas

Ouverte
  • Quelque chose ne va pas ?
#8,686 0 commentaires 0 réactions 0 personnes assignées Voir sur GitHub

Les mainteneurs répondent en général sous 1 jour

Personne n'a encore pris cette issue.

Évaluation

Difficulté
4/5
Temps estimé
3-5 jours
Accessibilité débutants
35/100
Type d'issue
Fonctionnalité
Clarté
Plutôt claire
Activité
Active
Stack technique
php
Domaine
api

Piste de recherche

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.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

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.

Langage dominant
PHP
Étoiles
2.6k
Forks
989
Merge moyen
2 j 2 h
PR mergées (30 j)
101

Préparer son environnement

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Autres issues de api-platform/core

Toutes les issues de api-platform/core

Issues similaires

Plus d'issues PHP

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.