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

[armanist]

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:

• #546
• #548