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

Support nested module-relative controller resolution in routes while preserving explicit controller class references

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

Nadie ha tomado este issue todavía.

Evaluación

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

Línea de trabajo

Comienza rastreando la resolución del controlador a través de src/Router/RouteBuilder.php y src/Router/RouteDispatcher.php; después, inspecciona src/Router/Route.php y los metadatos de la ruta de la request y las rutas de listado de rutas. Verifica cadenas de controlador planas, anidadas relativas al módulo y explícitamente totalmente cualificadas durante el dispatch, el listado de rutas y los metadatos; añade pruebas para cada caso y confirma que el comportamiento plano existente se mantiene intacto.

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

Descripción

routing

Summary

Enhance Quantum route controller resolution so route definitions can reference controllers in nested subnamespaces/folders within the current module, while preserving existing support for explicit fully qualified controller class references.

This should allow controller route strings such as:

  • PostController
  • V1\PostController
  • Admin\UserController

to resolve relative to the current module’s Controllers namespace, without breaking the ability to use explicit FQCN controller class strings where intentionally supported.

Why

Current route controller resolution in Quantum is too limited for deeper controller organization.

Today, flat shorthand works for controllers that live directly under:

  • {Module}\Controllers\...

However, the current resolution logic uses a simple backslash check to decide whether a handler should be prefixed with the module controller namespace.

That means a nested relative controller path such as:

  • V1\PostController

is currently treated the same way as an explicitly qualified controller class string, even though those are different use cases.

As a result, Quantum lacks a clean way to organize controllers inside nested subnamespaces within the current module.

Goal

Allow nested controller organization inside a module while preserving both:

  • current flat controller shorthand
  • intentional explicit FQCN controller class references

Proposed Direction

Update route controller resolution so it can distinguish between:

Module-relative controller shorthand

Examples:

  • PostController
  • V1\PostController
  • Admin\UserController

These should resolve relative to the current module’s Controllers namespace.

Examples:

  • PostController
    resolves to:

    • {ModuleBaseNamespace}\{CurrentModule}\Controllers\PostController

  • V1\PostController
    resolves to:

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

  • Admin\UserController
    resolves to:

    • {ModuleBaseNamespace}\{CurrentModule}\Controllers\Admin\UserController
Explicit FQCN controller references

If the route handler is intentionally written as an explicit fully qualified controller class string, that behavior should remain supported.

Examples:

  • \Modules\Api\Controllers\V1\PostController
  • Modules\Api\Controllers\V1\PostController

The resolution logic should therefore no longer use “contains backslash” as the only distinction between shorthand and explicit controller references.

Instead, it should distinguish properly between:

  • nested module-relative controller paths
  • explicit FQCN controller class references

Why this matters

This is a prerequisite for cleaner future work such as:

  • API major versioning within a single module
  • better controller organization in larger modules
  • route-set mounting with version-specific controller subnamespaces

without forcing:

  • flat controller folders
  • duplicated route definitions
  • awkward controller naming workarounds

Acceptance Criteria

  • flat controller shorthand continues to work
  • nested controller shorthand such as V1\PostController and Admin\UserController resolves correctly within the current module
  • explicit FQCN controller class references remain supported if intentionally provided
  • route listing, dispatch, and request route metadata continue to work with nested resolved controllers
  • controller resolution no longer relies solely on “contains backslash” to decide whether a handler is relative or explicit
  • tests verify flat controller shorthand resolution such as PostController
  • tests verify nested module-relative controller shorthand such as V1\PostController
  • tests verify explicit FQCN controller class references continue to resolve correctly

Notes

Relevant code:

  • src/Router/RouteBuilder.php
  • src/Router/RouteDispatcher.php
  • src/Router/Route.php
  • src/Http/Traits/Request/Route.php
  • src/Console/Commands/RouteListCommand.php

This ticket should be treated as a routing foundation improvement and a prerequisite for cleaner API versioning support inside a single module.

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.