All redirect management in the admin screens and through the abilities is gated on a single
custom capability, manage_redirects. WP-CLI is trusted by virtue of being WP-CLI and does
not check it.
The plugin grants it to the administrator and editor roles on the first request of any kind after installation: front end, admin, REST or WP-CLI. The grant is version-gated, so it runs once rather than on every request, and it is written to the roles in the database — which means deactivating the plugin leaves it in place, as WordPress core does for any plugin's role capabilities. See Revoking it if you need it gone.
One add_cap() call is the whole switch. Every primitive capability on the redirect post
type maps to manage_redirects, so there is nothing else to grant:
$role = get_role( 'shop_manager' );
if ( $role instanceof WP_Role ) {
$role->add_cap( 'manage_redirects' );
}On WordPress VIP, use the platform helper instead, which handles the role change safely across the fleet:
wpcom_vip_add_role_caps( 'shop_manager', 'manage_redirects' );Either call only needs to run once, not on every page load. Role changes are persisted to
the database, so the usual pattern is to run it from a one-off migration, a WP-CLI
command, or a plugin activation hook rather than from a theme's functions.php.
To grant it to a single user rather than a role:
$user = get_user_by( 'email', 'someone@example.com' );
if ( $user instanceof WP_User ) {
$user->add_cap( 'manage_redirects' );
}The plugin never removes the capability itself, so revoking it is the same WP_Role call in
reverse:
$role = get_role( 'editor' );
if ( $role instanceof WP_Role ) {
$role->remove_cap( 'manage_redirects' );
}On WordPress VIP, use the platform helper:
wpcom_vip_remove_role_caps( 'editor', 'manage_redirects' );From WP-CLI, core's cap command does the same without any code:
wp cap remove editor manage_redirectsA revocation sticks. The plugin records that it has granted the capability in the
manage_redirects_capability_version option, and while that option is current it does not
grant it again, so an editor you have revoked stays revoked across later requests. The
exception is a future release that bumps that version to grant something new, which would
grant it to both default roles again.
To clear everything the plugin wrote to the roles — before deleting the plugin, say — revoke it from both default roles and delete that option:
wp cap remove administrator manage_redirects
wp cap remove editor manage_redirects
wp option delete manage_redirects_capability_versionDelete the option only if the plugin is going away. With the plugin still active, the next
request sees no option and grants the capability to administrators and editors again.
On a multisite network, roles are stored per site, so run the commands against each site with
--url.
There is no view-only capability. manage_redirects covers reading the redirect list as
well as changing it, and the read-only abilities require it too.
This is deliberate: the redirect list is a map of a site's old and new URL structure, and includes destinations that may not be published yet. Authors and contributors are not given access to it, and the post type is registered so that WordPress's auto-generated "Add New" submenu never appears for users who cannot manage redirects.
All of this plugin's filters use the legacy_redirector_ prefix. The four that shipped
before 2.0 were prefixed wpcom_legacy_redirector_; those names still work and emit a
deprecation notice naming the replacement. Where a callback is attached to both names, the
current name wins. UPGRADING.md has the full mapping.
| Filter | Purpose |
|---|---|
legacy_redirector_request_path |
Alter the request path before lookup |
legacy_redirector_destination_url |
Alter the resolved destination before redirecting |
legacy_redirector_redirect_status |
Change the HTTP status code |
legacy_redirector_redirect_max_age |
Change the Cache-Control lifetime |
legacy_redirector_preserve_query_params |
Carry named query parameters through to the destination |
legacy_redirector_allow_insert |
Allow creation from a context with no capable user |
legacy_redirector_check_destination_reachability |
Skip the admin form's HTTP check |
legacy_redirector_background_audit_seconds |
Tune or turn off the background check |
Every redirect is checked in the background for the problems its stored details can show (a destination post gone or unpublished, a host not allowed, a loop), so the "Has issues" view and the menu badge stay current without anyone pressing Validate all redirects. Nothing is requested over HTTP. Every five minutes, the check spends up to 20 seconds working through the table from where it last stopped. It starts a new pass at most once a day: a pass that finishes within a day waits until a day after it began, and one that takes longer is followed straight away by the next, never overlapping it. A site with a few thousand redirects is checked daily; one with millions takes longer per pass, and the list screen shows how long.
A redirect that points at a post by ID does not wait for the pass: it is flagged the moment that post is unpublished, trashed or deleted, and cleared when the post is published again.
Change the seconds per five minutes, or return 0 to turn the check off, for example on a
very large site that runs wp legacy-redirector validate off-peak instead:
add_filter( 'legacy_redirector_background_audit_seconds', function( $seconds ) {
return 5;
} );A query string is part of the lookup, so by default /old-page?utm_source=news does not
match the stored /old-page. To take named parameters out of the lookup and carry them
through to the destination:
add_filter( 'legacy_redirector_preserve_query_params', function( $params, $url ) {
return array( 'utm_source', 'utm_medium', 'utm_campaign' );
}, 10, 2 );The default is 301:
add_filter( 'legacy_redirector_redirect_status', function( $status, $url ) {
return 302; // Temporary redirect.
}, 10, 2 );Redirect responses carry a Cache-Control: max-age header so browsers do not cache them
indefinitely. The default is one day for permanent redirects and one minute otherwise:
add_filter( 'legacy_redirector_redirect_max_age', function( $max_age, $url, $status ) {
return HOUR_IN_SECONDS;
}, 10, 3 );Return 0 to suppress the header entirely, for example where an edge cache manages
redirect caching instead.
Logged-in users never get the header, whatever the filter returns, so their redirects keep the no-cache headers WordPress sends them.
The path is still percent-encoded at this point, because decoding happens during lookup:
add_filter( 'legacy_redirector_request_path', function( $path ) {
return strtolower( $path ); // Case-insensitive matching.
} );The counterpart to legacy_redirector_request_path: change the resolved destination
before the redirect is sent. Returning an empty string cancels the redirect.
This is mainly useful where a path suffix is stripped for lookup and needs re-adding to
the destination, such as the legacy /amp/ paired URL structure:
// Match /old-path/amp against the stored /old-path redirect, then re-append /amp.
add_filter( 'legacy_redirector_request_path', function( $path ) {
return preg_replace( '#/amp/?$#', '', $path );
} );
add_filter( 'legacy_redirector_destination_url', function( $destination, $path, $url ) {
return preg_match( '#/amp/?$#', $url ) ? trailingslashit( $destination ) . 'amp/' : $destination;
}, 10, 3 );If your site uses the AMP plugin's default query parameter structure (?amp=1) rather
than the path suffix, you do not need this — use
legacy_redirector_preserve_query_params with 'amp' instead.
WP-CLI is always allowed, and so is any user with manage_redirects, wherever the request
arrives from. Code running where neither is true — an unauthenticated front-end request,
for instance — is blocked unless this filter opts in:
add_filter( 'legacy_redirector_allow_insert', function( $allow ) {
return true;
} );Scope it as tightly as you can. Returning true unconditionally lets any front-end code
path create redirects.
When you save a redirect in the admin, the form makes an HTTP request to confirm a relative destination is not served as a 404. That is the right default, but it is wrong for a site whose valid destinations legitimately 404 for an anonymous visitor — members-only content, geo-gated pages, or content staged ahead of launch:
add_filter( 'legacy_redirector_check_destination_reachability', function( $check ) {
return false;
} );WP-CLI and the abilities are unaffected; this only governs the admin form.
A redirect to another domain only works if WordPress is willing to send visitors there.
Allow the host with core's allowed_redirect_hosts filter:
add_filter( 'allowed_redirect_hosts', function( $hosts ) {
$hosts[] = 'other-domain.example.com';
$hosts[] = 'www.other-domain.example.com';
return $hosts;
} );Note that www. is a different host and needs listing separately.
Creating or updating a redirect to a host the site does not allow is an error naming the domain, so you find out at the point of creation. A redirect that was already stored before the host was removed from the list leaves the original 404 in place rather than sending visitors anywhere unexpected.
wp legacy-redirector find-domains lists every domain your existing destinations point
at, which is the quickest way to audit the list you need.
Live destination checks — the admin Test action and wp legacy-redirector test — use
WordPress's safe HTTP functions, which refuse to request loopback, private, and reserved IP
addresses. The site's own host is always allowed.
When a destination redirects, the check follows up to five hops, but only to the site's own
host and hosts in allowed_redirect_hosts. A hop to any other host is not requested: the
destination has answered, so it passes. More than five hops is reported as a failed request.
If your redirects legitimately point at other internal hosts, such as an intranet or a staging network, allow them with core's filter:
add_filter( 'http_request_host_is_external', function( $external, $host ) {
return 'internal.example.test' === $host ? true : $external;
}, 10, 2 );Even with this filter, safe requests only use ports 80, 443, and 8080, plus the site's own port. Destinations on other ports report as failed in validation; the redirects themselves still work.
The plugin's text domain is legacy-redirector. It is not on WordPress.org, so there are no
language packs and the plugin bundles no translations. To show the admin screens in another
language, supply your own files, named for the text domain and locale, in the plugin
translations folder:
wp-content/languages/plugins/legacy-redirector-de_DE.mo
wp-content/languages/plugins/legacy-redirector-de_DE.l10n.php
WordPress loads them from there on its own; the plugin needs no setting. The .l10n.php file
is optional but loads faster, and WordPress prefers it when both exist. On WordPress VIP,
commit them to languages/plugins/ in your site's repository.
Start from the translation template, languages/legacy-redirector.pot, which each release
includes. Translate it in a tool such as Poedit, then build the compiled files with WP-CLI:
wp i18n make-mo legacy-redirector-de_DE.po
wp i18n make-php legacy-redirector-de_DE.poSome text stays in English whatever the site's language:
- WP-CLI output, on purpose, so scripts and logs read the same everywhere.
- Why a stored row cannot be read.
- Messages that come from outside the plugin, such as an HTTP request's error, which are in whatever language their source uses.
Deleting the plugin from the Plugins screen runs its uninstall.php, which removes only what
the plugin can rebuild: the background check's progress, counts, and lock
(legacy_redirector_audit_sweep, legacy_redirector_audit_flag_counts,
legacy_redirector_audit_flags_checked_at, legacy_redirector_audit_lock), its scheduled
event (legacy_redirector_scheduled_audit), and the two transients that hold the migration's
web batches back (wpcom_legacy_redirector_upgrade_cli, wpcom_legacy_redirector_upgrade_backoff).
On a multisite network it does this on every site.
Sites that load the plugin in code, as on WordPress VIP, never run uninstall.php. Removing
the code leaves everything in place.
Everything else is kept on purpose, so reinstalling picks up where it left off:
| What | Stored as | Why it is kept |
|---|---|---|
| Redirects, including trashed ones | vip-legacy-redirect posts |
A redirect map is expensive to rebuild |
| Per-redirect state | Post meta on those posts: _legacy_redirector_audit_issues, _legacy_redirector_duplicate_of, _legacy_redirector_duplicate_never_fired, _legacy_redirector_upgrade_waits_for |
It describes the redirects, and goes when they do |
| Migration state | wpcom_legacy_redirector_db_version, plus wpcom_legacy_redirector_upgrade_* options while a migration is unfinished |
Without the version, a reinstall would treat 2.0 redirects as 1.x data and migrate them again |
| The capability | manage_redirects on the administrator and editor roles, and manage_redirects_capability_version |
Roles may have been changed deliberately; see Revoking it |
To remove all of it once the plugin is gone for good, delete the redirects (their meta goes with them), then the migration options, then the capability:
wp post list --post_type=vip-legacy-redirect --post_status=any,trash --format=ids \
| xargs -r -n 1000 wp post delete --force
wp option list --search='wpcom_legacy_redirector_*' --field=option_name \
| xargs -r -n 1 wp option delete
wp cap remove administrator manage_redirects
wp cap remove editor manage_redirects
wp option delete manage_redirects_capability_versionDeleting redirects cannot be undone. If there is any chance you will want them back, export them first while the plugin is still installed; see Export and back up.
On a multisite network, run the commands against each site with --url.