Support nested module-relative controller resolution in routes while preserving explicit controller class references
Maintainers usually reply within 1 day
Nobody has claimed this yet.
Assessment
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Newbie friendliness
- 64/100
Research direction
Start by tracing controller resolution through src/Router/RouteBuilder.php and src/Router/RouteDispatcher.php, then inspect src/Router/Route.php and the request route metadata and route-listing paths. Verify flat, nested module-relative, and explicit fully qualified controller strings across dispatch, route listing, and metadata; add tests for each case and confirm existing flat behavior remains intact.
Written by the indexing model from the issue text.
Description
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:
PostControllerV1\PostControllerAdmin\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:
PostControllerV1\PostControllerAdmin\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\PostControllerModules\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\PostControllerandAdmin\UserControllerresolves 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.phpsrc/Router/RouteDispatcher.phpsrc/Router/Route.phpsrc/Http/Traits/Request/Route.phpsrc/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.
- Dominant language
- PHP
- Stars
- 43
- Forks
- 22
- Avg merge
- 54m
- Merged PRs (30d)
- 57
Getting set up
- No Dockerfile or Docker Compose file
- No pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from quantum-php/framework
-
bug good first issue
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
quantum-php/framework#692 ·
Maintainers usually reply within 1 day
-
routing testing
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
quantum-php/framework#547 ·
Maintainers usually reply within 1 day
-
bug
Difficulty 3/5 1-2 days Newbie friendliness 72/100
quantum-php/framework#694 ·
Maintainers usually reply within 1 day
-
refactoring tech debt
Difficulty 5/5 Over a week Newbie friendliness 20/100
quantum-php/framework#693 ·
Maintainers usually reply within 1 day
-
install:debugbar reads the package folder from the working directory and uses the default storage adapterPossibly taken @armanist claimed this today. Openbug console debugbar good first issue
quantum-php/framework#691 · 1 assignee ·
Maintainers usually reply within 1 day
All issues in quantum-php/framework
Similar issues
-
Difficulty 1/5 Under an hour Newbie friendliness 70/100
ajeetraina/awesome-docker-sbx#559 ·
-
dependencies enhancement
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
novalo-dev/Prestashop-MCP-Server#329 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 80/100
Maintainers usually reply within 1 day
-
bug origin:interactive status:available
Difficulty 2/5 1-3 hours Newbie friendliness 62/100
Ultimate-Multisite/ultimate-multisite#2131 ·
Maintainers usually reply within 1 day
-
sync-en
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
Maintainers usually reply within 1 day