Add first-class special route token support for framework-owned URL segments such as @lang and @version
还没有人认领这个 Issue。
评估
调研方向
先阅读 src/Router/PatternCompiler.php 和 src/Router/RouteBuilder.php，然后跟踪 src/Router/Route.php、MatchedRoute.php、RouteDispatcher.php 以及 src/Http/Traits/Request/Route.php 如何编译、匹配并暴露路由值。完成的标准是：@version/@lang 等保留 token 可以在同一个 pattern 中共存，在不进行默认 action 绑定的情况下到达路由上下文，并保持普通参数不变，同时测试覆盖解析、匹配和上下文行为。
由索引模型根据 Issue 内容生成。
描述
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
@langrouting support - explicit
@versionAPI 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.phpsrc/Router/RouteBuilder.phpsrc/Router/Route.phpsrc/Router/MatchedRoute.phpsrc/Router/RouteDispatcher.phpsrc/Http/Traits/Request/Route.php
This ticket should be treated as the routing foundation for future explicit @lang and @version support.
- 主要语言
- PHP
- 星标
- 36
- 派生
- 22
- PR 合并指标
- 30 天内没有已合并 PR
环境准备
- 没有 Dockerfile 或 Docker Compose 文件
- 没有 Pull Request 模板
- 阅读贡献指南
从这里开始
- 先读完整个 Issue，再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库，在一个分支上完成修改。
- 提交 Pull Request，并在描述里引用这个 Issue 编号。
quantum-php/framework 的其他 Issue
-
routing testing
难度 2/5 1-3 小时 新手友好度 76/100
quantum-php/framework#547 ·
-
view
难度 1/5 1 小时以内 新手友好度 75/100
quantum-php/framework#542 ·
-
enhancement http
难度 5/5 一周以上 新手友好度 35/100
quantum-php/framework#565 · 1 条评论 ·
-
components view
难度 5/5 一周以上 新手友好度 42/100
quantum-php/framework#551 ·
-
Add explicit @version special route token support for API major versioning within a single module未关闭routing
难度 5/5 一周以上 新手友好度 45/100
quantum-php/framework#550 ·
查看 quantum-php/framework 的全部 Issue
相似的 Issue
-
难度 2/5 1-3 小时 新手友好度 72/100
filamentphp/filament#20630 ·
维护者通常 1 天内回复
-
Issue: Bug
难度 2/5 1-3 小时 新手友好度 82/100
OpenAPITools/openapi-generator#25107 ·
维护者通常 1 天内回复
-
needs-maintainer-review review:approve
难度 2/5 1-3 小时 新手友好度 68/100
Ultimate-Multisite/ultimate-ai-connector-compatible-endpoints#163 ·
维护者通常 1 天内回复
-
难度 2/5 1-3 小时 新手友好度 78/100
-
Bug
难度 2/5 1-3 小时 新手友好度 88/100
维护者通常 1 天内回复