Routing + redirection clarifications

Author: AugustMiller

docs/5.x/configure.md

@@ -33,7 +33,8 @@ The most common way to customize your Craft project is by editing files in the [
 | [General Configuration](#general) | `general.php` | Global options that can affect the front-end, control panel, debugging, etc.
 | [Database Settings](#database) | `db.php` | Connection settings for your database.
 | [Custom Options](#custom-settings) | `custom.php` | Arbitrary key-value storage for your own options.
-| [Routing](#url-rules) | `routes.php`, `redirects.php` | Custom HTTP routes and redirect rules.
+| [Routing](#url-rules) | `routes.php` | Custom HTTP routes.
+| [Redirection](system/routing.md#redirection) | `redirects.php` | Additional patterns for redirection.
 | [Application Configuration](#application-configuration) | `app.php`, `app.web.php`, `app.console.php` | Overrides for the root application and any of its [Components](https://www.yiiframework.com/doc/guide/2.0/en/concept-components).
 | Plugin Settings | `{plugin-handle}.php`, or other custom files | Consult the plugin’s documentation for specifics.
 | [Advanced](#advanced) | | Specific library options and/or behaviors that may be exposed in a non-standard way.
@@ -483,7 +484,7 @@ Your [database connection settings](reference/config/db.md) are set via the `con
 
 You can define custom [URL rules](guide:runtime-routing#url-rules) in `config/routes.php`, and [redirection rules](system/routing.md#redirection) in `config/redirects.php`. <Since ver="5.6.0" feature="Redirection rules" />
 
-See [Routing](system/routing.md) for more details.
+See [Routing](system/routing.md) for more details about Craft’s request handling behavior.
 
 ### Application Configuration
 

docs/5.x/system/routing.md

@@ -299,6 +299,10 @@ return [
 ];
 ```
 
+::: tip
+To send a user to the homepage, use an empty string (`''`) for the `to` value.
+:::
+
 Rules can contain [parameters](#advanced-routing-with-url-rules), as well:
 
 ```php
@@ -315,6 +319,12 @@ If you need complete control over the matching _and_ redirection logic, create a
 return [
     [
         'match' => function (\Psr\Http\Message\UriInterface $url): ?string {
+            // Match a path:
+            if ($url->getPath() !== 'customer_order.aspx') {
+                return null;
+            }
+
+            // Or test for the presence of a query parameter:
             parse_str($url->getQuery(), $params);
 
             if (!isset($params['orderId'])) {
@@ -328,4 +338,26 @@ return [
 ];
 ```
 
-You may return `null` from a match callback to skip the rule and continue processing.
+You may return `null` from a match callback to skip the rule and continue processing. Callbacks are only invoked if all previous rules fail to match.
+
+#### Multi-Site Redirection
+
+Unlike routes, redirection rules are processed globally, and matched against full paths. For example, a rule like `old/page` would _not_ catch a request path beginning with a site’s base path, like `/secondary-site/old/page`. You may parameterize rules to match multiple sites’ base paths (i.e: `<site:{slug}>/old/page`), or define individual rules for each relevant site.
+
+However, as part of Craft’s normal routing behavior, every front-end request is handled in the context of a site—typically one with the correct hostname and the longest matching base path, or the “default” site when none match. When a redirect rule is evaluated, its `to` value is treated as site-relative, meaning this rule…
+
+```php
+return [
+    'corporate/team' => 'about-us',
+];
+```
+
+…behaves differently depending on whether or not a site exists with the base path `corporate`. _Without_, it would redirect normally (`/corporate/team` to `/about-us`), but _with_, requests to `/corporate/team` would actually end up at `/corporate/about`, because Craft tried to route the request in the “Corporate” site context.
+
+To avoid this ambiguity, prefix the destination with a slash (`/`) to make it an “absolute” path:
+
+```php
+return [
+    'corporate/team' => '/about-us',
+];
+```