Document trailing slash canonical redirects#472
Open
samdark wants to merge 1 commit into
Open
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
Adds guidance to the routing guide on handling canonical URLs for trailing slashes, including an example PSR-15 middleware to normalize paths before routing.
Changes:
- Document why
/docsvs/docs/should be normalized for SEO/caching consistency. - Add a
RemoveTrailingSlashMiddlewareexample that redirects to a canonical, non-trailing-slash URL using HTTP 308. - Explain where to register the middleware in the application middleware stack.
Comment on lines
+309
to
+310
| The following middleware removes trailing slashes, preserves the query string, drops the fragment, and uses `308 | ||
| Permanent Redirect` so the HTTP method is preserved: |
Comment on lines
+324
to
+346
| use Yiisoft\Http\Header; | ||
| use Yiisoft\Http\Status; | ||
|
|
||
| final readonly class RemoveTrailingSlashMiddleware implements MiddlewareInterface | ||
| { | ||
| public function __construct( | ||
| private ResponseFactoryInterface $responseFactory, | ||
| ) { | ||
| } | ||
|
|
||
| public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface | ||
| { | ||
| $uri = $request->getUri(); | ||
| $path = $uri->getPath(); | ||
|
|
||
| if ($path !== '/' && str_ends_with($path, '/')) { | ||
| $canonicalUri = $uri | ||
| ->withPath(rtrim($path, '/')) | ||
| ->withFragment(''); | ||
|
|
||
| return $this->responseFactory | ||
| ->createResponse(Status::PERMANENT_REDIRECT) | ||
| ->withHeader(Header::LOCATION, (string) $canonicalUri); |
samdark
commented
May 31, 2026
| ]; | ||
| ``` | ||
|
|
||
| ### Trailing slash canonical URLs |
Member
Author
There was a problem hiding this comment.
- It's better to be done via webserver config.
- Don't we have a middlware for it? Seems not.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Verification
yiisoft/apptemplate created withcomposer create-project yiisoft/app /tmp/yii-docs-upload-app --no-interactionRemoveTrailingSlashMiddlewareandverify-trailing-slash-canonical.phpto the template appphp -l src/Web/Middleware/RemoveTrailingSlashMiddleware.php && php -l verify-trailing-slash-canonical.phpphp verify-trailing-slash-canonical.php; verified/docs/?page=2#headingredirects with 308 to/docs?page=2and root/passes throughvendor/bin/phpstan analyse src/Web/Middleware/RemoveTrailingSlashMiddleware.php verify-trailing-slash-canonical.php --level=max --no-progressvendor/bin/psalm --no-cache --output-format=console src/Web/Middleware/RemoveTrailingSlashMiddleware.php verify-trailing-slash-canonical.phpnpx markdown-link-check src/guide/runtime/routing.mdnpm run build