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

[armanist]

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.