Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

[QueryParameter] Support PHP backed enums in OpenAPI schemas

Aperta
  • Qualcosa non va?
#8,686 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
35/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
php
Ambito
api

Direzione di ricerca

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.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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.

Lingua principale
PHP
Stelle
2.6k
Fork
989
Merge medio
2g 4h
PR unite (30g)
90

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di api-platform/core

Tutte le issue di api-platform/core

Issue simili

Altre issue su PHP

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.