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

Add explicit @version special route token support for API major versioning within a single module

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

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
45/100
Tipo de issue
Nueva funcionalidad
Claridad
Bastante claro
Estado de actividad
Tranquilo
Stack tecnológico
php
Área
api, backend

Línea de trabajo

Empieza siguiendo el manejo de @version en src/Router/PatternCompiler.php, src/Router/RouteBuilder.php, src/Router/RouteDispatcher.php, src/Router/MatchedRoute.php y src/Http/Traits/Request/Route.php; inspecciona primero las plantillas de DemoApi y las dependencias #546 y #548. Se considera terminado cuando las versiones principales configuradas y compatibles coincidan, los controladores conscientes de la versión se resuelvan dentro de un módulo, los valores de versión sigan siendo parte del contexto de la ruta y las pruebas cubran la coincidencia y la resolución.

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

Descripción

routing

Summary

Add API major versioning support based on the explicit special route token:

  • @version

so a single API module can expose multiple major API versions concurrently, such as:

  • /api/v1/posts
  • /api/v2/posts

without treating each version as a separate module.

Why

Quantum needs a clean framework-level API versioning model.

The intended ownership model is:

  • one logical Api module
  • multiple supported API major versions inside that module

With the special route token foundation in place, versioning can be expressed explicitly in route patterns instead of relying on:

  • duplicated route trees
  • positional URL conventions
  • separate modules per version
  • hidden dispatch tricks

Goal

Allow routes to explicitly declare API major version position using:

  • @version

and let the framework treat the matched version as framework-owned route context for version-aware controller resolution.

Proposed Direction

API routes that are versioned should explicitly include:

  • @version

Examples:

$route->get('@version/posts', 'PostController', 'posts');
$route->get('@version/post/[uuid=:any]', 'PostController', 'post');
$route->post('@version/signin', 'AuthController', 'signin');

This should allow URLs such as:

  • /api/v1/posts
  • /api/v2/posts
  • /api/v1/signin

depending on module prefix configuration and supported versions.

Config Direction

Supported API versions should be declared in module config.

A likely shape is:

'Api' => [
    'prefix' => 'api',
    'enabled' => true,
    'versions' => ['v1', 'v2'],
]

The route token:

  • @version

should then match only those configured supported versions.

Controller Resolution Direction

Matched version values should be used by the framework to resolve version-specific controllers inside the same module.

Examples:

  • v1 + PostController
    resolves to:

    • {ModuleBaseNamespace}\Api\Controllers\V1\PostController

  • v2 + PostController
    resolves to:

    • {ModuleBaseNamespace}\Api\Controllers\V2\PostController

This allows one route shape to map to different major-version controller implementations inside a single module.

Important behavior

The resolved version should be:

  • matched through the @version token
  • validated against configured supported versions
  • made available to framework internals as version route context
  • used for version-aware controller resolution
  • kept distinct from ordinary controller action parameters by default

Scope

This ticket should focus on major API versioning only.

It should not introduce:

  • minor or patch versioning in the URL
  • header-based minor/patch runtime negotiation
  • separate modules per API version

Minor and patch changes should remain outside the first implementation scope.

Acceptance Criteria

  • routes can explicitly declare API version position using @version
  • matched @version values are validated against configured supported versions
  • a single API module can expose multiple supported major versions concurrently
  • matched version values are used for version-aware controller resolution within the same module
  • routed version values do not become ordinary positional controller action parameters by default
  • tests cover @version route matching and version-aware controller resolution behavior
  • templates and examples can be updated to use @version where appropriate

Notes

Relevant code:

  • src/Router/PatternCompiler.php
  • src/Router/RouteBuilder.php
  • src/Router/RouteDispatcher.php
  • src/Router/MatchedRoute.php
  • src/Http/Traits/Request/Route.php
  • src/Module/Templates/DemoApi

This ticket depends on:

Lenguaje dominante
PHP
Estrellas
36
Forks
22
Sin PR fusionados en 30 d

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 quantum-php/framework

Todos los issues de quantum-php/framework

Issues similares

Más issues de PHP

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.