Add first-class special route token support for framework-owned URL segments such as @lang and @version

[armanist]

Summary

Add first-class router support for framework-owned special route tokens such as:

• @lang
• @version

so route definitions can explicitly declare special URL segments in a clear, semantic, and framework-native way.

Why

Quantum currently handles special routing concerns inconsistently.

For example:

• language URL handling relies on config-driven segment position detection
• API versioning has no clean framework-level model yet

This makes special URL segments feel implicit, positional, and harder to reason about than ordinary route structure.

A better model is to let routes explicitly declare framework-owned special segments in the route pattern itself.

Examples:

$route->get('@lang/posts', 'PostController', 'posts');
$route->get('@version/posts', 'PostController', 'posts');
$route->get('@version/@lang/posts', 'PostController', 'posts');

This makes route semantics explicit while allowing the framework to treat those segments differently from ordinary user-defined route parameters.

Goal

Introduce a routing foundation that supports reserved special route tokens for framework-level concerns.

This foundation should make it possible for Quantum to support explicit special URL segments without relying on brittle positional config or ad hoc route conventions.

Proposed Direction

Support reserved route tokens inside route patterns, beginning with the concept of framework-owned segments such as:

• @lang
• @version

These tokens should be recognized by the router as special routing constructs rather than ordinary route parameters.

The framework should be able to:

• recognize these tokens during route compilation
• match them correctly during request routing
• attach their resolved values to framework route context
• keep them distinct from normal action parameters unless explicitly intended otherwise

Important behavior

Special route tokens should be treated differently from ordinary route params.

They should be:

• framework-reserved
• semantically meaningful
• available to framework internals such as language detection or version-aware controller resolution
• prevented from behaving like ordinary positional controller action arguments by default

Initial scope

This ticket is the router foundation only.

It should establish the special-token mechanism itself, not fully implement every feature that may use it.

Follow-up features can then build on this foundation, including:

• explicit @lang routing support
• explicit @version API routing support

Acceptance Criteria

• the router supports reserved special tokens inside route patterns
• special tokens are recognized during route compilation and matching
• matched special-token values are available to framework internals as route context
• special-token values are kept distinct from ordinary controller action parameter binding by default
• the routing system can support multiple special tokens in one path, such as @version/@lang/posts
• tests cover special-token parsing, matching, and route context behavior
• existing ordinary route parameter behavior remains intact

Notes

Relevant code:

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

This ticket should be treated as the routing foundation for future explicit @lang and @version support.