Redirect manager

Admin → System → Redirects (/admin/redirects, or the equivalent configured admin URL). Create or edit a rule, choose its status and destination, and save; disable a managed rule to stop applying it. Changes and CSV imports are recorded in the administrative audit log. Migration 0025_redirect_manager adds the rules and aggregate 404 tables for PostgreSQL, MySQL, and MariaDB, and normal startup applies it.

Matching and precedence#

Redirects apply to GET and HEAD requests before public content rendering and HTML cache lookup, and they intentionally override existing public content URLs. Static assets, platform routes (the configured admin path, API, and locale-prefixed reserved paths), and registered plugin routes take precedence; preview requests and other HTTP methods bypass the manager. Rules match the full case-sensitive, URL-encoded path including any locale prefix — /old and /nl-NL/old are different sources.

Priority is exact path, then longest prefix, then regex (longest source expression, then stable rule ID). Automatic permalink history runs after managed rules. Each source / match-type combination must be unique, including disabled rules, and a site supports up to 1,000 managed rules.

A prefix ends in / — enter /old/, not /old/*; $1 is the suffix. Regex sources are limited to 512 characters and must start with ^/ and end with $. Supported syntax is literal ASCII letters and digits, /, _, %, ~, -, the segment captures ([^/]+) and (\d+), and an optional final (.*); up to nine captures are referenced as $1–$9. Alternation, arbitrary quantifiers, nested groups, backreferences, lookarounds, and flags are rejected to keep public matching bounded.

Only the Plain permalink identity query (?p=<id>) participates in matching. Other incoming query parameters are dropped when a managed redirect applies, so put any fixed query parameters in the destination. Sources cannot contain fragments or arbitrary query strings, and captures come from the pathname only.

Destinations and chains#

Choose an internal absolute path, a published content item in an active locale, or an absolute HTTP(S) URL. A content target stores the content ID and resolves its current canonical URL; if that content becomes unavailable the rule does not redirect. External URLs cannot contain credentials or a dynamic host, and protocol-relative URLs, backslashes, traversal, and encoded control characters are rejected — including after capture substitution.

Choose 301, 302, 307, or 308. The manager checks the combined rules and historical permalink redirects for cycles before saving, and conservatively rejects pattern combinations that *could* form one; chains over 32 hops are rejected. Equal-status chains collapse during evaluation without rewriting stored rules — /a → /b → /c, all 301, returns one 301 to /c — while mixed-status chains keep their hops. A cycle introduced by a later content or configuration change, an unsafe expansion, or more than 32 hops makes the managed redirect fall through to normal routing.

URL change suggestions#

Slug and permalink-structure changes already retain historical published URLs and serve automatic 301s (see Permalinks). The URL change suggestions section surfaces those known old content and taxonomy URLs. Review a suggestion to prefill a managed rule and pick a different status or destination; saving an enabled exact rule overrides the historical redirect, and disabling it restores automatic handling. Unpublished or deleted targets and ambiguous old URLs are not suggested.

404 reporting#

The 404 log shows path, hit count, latest referrer, and first / last seen. Create redirect from this 404 prefills the source and focuses the destination field. Only finished public GET responses with status 404 are recorded (cached 404s included); reserved routes, previews, HEAD, and non-GET requests are excluded. Query strings, fragments, IP addresses, and user agents are not stored, and referrers retain only origin and path. Storage is capped at 10,000 distinct paths per site; entries older than 30 days are hidden on read and pruned on later writes. Counts may underreport during overload, and a logging failure never changes the public response.

CSV and API#

Export downloads the current managed rules, disabled ones included. Import accepts up to 500 rows and 1 MiB per request; every row validates before the transaction writes anything, and a duplicate source or a loop rejects the whole import. Import adds rules — it never replaces existing ones.

source,kind,targetType,target,status,enabled
/old-page,exact,internal,/new-page,301,true
/old/,prefix,external,https://example.org/archive/$1,308,true

All API operations require an administrator session and normal API CSRF protection for writes — there is no anonymous or API-key path — and the API is limited to 120 requests/minute per client. Audit actions are redirect.created, redirect.updated, redirect.imported, and redirect.logs_cleared.