Refactor language URL routing to use explicit @lang special route tokens instead of positional segment detection
还没有人认领这个 Issue。
评估
调研方向
先阅读 src/Router/PatternCompiler.php、src/Router/MatchedRoute.php、src/Http/Traits/Request/Route.php 和 src/Lang/Factories/LangFactory.php，然后检查现有的路由测试。跟踪路由 token 和语言解析目前的工作方式。当 @lang 路由能够匹配受支持的语言，将语言保留为路由上下文而不是普通参数，并且具备相应的测试以及在需要时更新的模板或示例时，即视为完成。
由索引模型根据 Issue 内容生成。
描述
Summary
Refactor Quantum language URL routing so routes can explicitly declare language segments using the special route token:
@lang
instead of relying on positional URL segment detection through config such as lang.url_segment.
Why
Current language URL handling is implicit and positional.
Today, language detection relies on config-driven segment index logic, for example:
lang.url_segment
and the framework then tries to detect the language by reading a configured request segment position, with additional prefix-aware adjustment logic.
That works, but it has several weaknesses:
- route structure does not explicitly show where language lives
- language handling depends on URL segment position math
- routes are harder to reason about when combined with prefixes or other special segments
- the model does not align with the new special route token direction
With special route token support in place, language routing should become explicit in the route pattern itself.
Goal
Allow routes to explicitly declare the language segment using:
@lang
so the router can treat language as a framework-owned route context rather than a positional URL convention.
Proposed Direction
Routes that are language-aware should explicitly include:
@lang
Examples:
$route->get('@lang/posts', 'PostController', 'posts');
$route->get('@lang/post/[uuid=:any]', 'PostController', 'post');
This should allow URLs such as:
/en/posts/es/posts
or, when module prefix is present:
/web/en/posts/api/en/posts
depending on module prefix configuration.
Config Direction
Language config should continue to define language behavior such as:
- whether language is enabled
- supported languages
- default language
But routed language placement should no longer depend on positional config like:
lang.url_segment
The route itself should explicitly declare where language lives.
Important behavior
The resolved language should be:
- matched through the
@langtoken - validated against configured supported languages
- made available to framework internals as language route context
- kept distinct from ordinary controller action parameters by default
Migration Direction
This feature should replace routed language URL detection based on positional segment config for routes that adopt @lang.
Backward compatibility strategy can be decided during implementation, but the intended direction is for explicit routed language segments to become the preferred and cleaner model.
Acceptance Criteria
- routes can explicitly declare language position using
@lang - matched
@langvalues are validated against configured supported languages - language route context is resolved through
@langrather than positional URL segment detection for token-based routes - routed language values do not become ordinary positional controller action parameters by default
- tests cover
@langroute matching and language resolution behavior - templates and examples can be updated to use
@langwhere appropriate
Notes
Relevant code:
src/Lang/Factories/LangFactory.phpsrc/Router/PatternCompiler.phpsrc/Router/MatchedRoute.phpsrc/Http/Traits/Request/Route.php- module route templates currently using language-prefixed route patterns
This ticket depends on:
- 主要语言
- 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
-
bug No Code Attached Yet
难度 2/5 1-3 小时 新手友好度 88/100
joomla/joomla-cms#48556 · 1 条评论 ·
维护者通常 1 天内回复
-
sync-en
难度 1/5 1 小时以内 新手友好度 92/100
维护者通常 1 天内回复
-
sync-en
难度 2/5 1-3 小时 新手友好度 74/100
维护者通常 3 天内回复
-
Перевод устарел
难度 1/5 1-3 小时 新手友好度 88/100
-
Form
难度 2/5 1-3 小时 新手友好度 74/100
symfony/symfony-docs#23159 ·
维护者通常 3 天内回复