Skip to content

Latest commit

 

History

History
364 lines (270 loc) · 14.7 KB

configuration.md

File metadata and controls

364 lines (270 loc) · 14.7 KB

Configuration

Permissions

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.

Granting it to another role

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' );
}

Revoking it

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_redirects

A 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_version

Delete 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.

Read-only access is not separable

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.

Filters

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

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;
} );

Preserve query parameters

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 );

Change the status code

The default is 301:

add_filter( 'legacy_redirector_redirect_status', function( $status, $url ) {
	return 302; // Temporary redirect.
}, 10, 2 );

Change the cache lifetime

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.

Alter the request path

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.
} );

Alter the destination

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.

Allow creation with no capable user

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.

Skip the admin form's reachability check

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.

External destinations

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.

Testing destinations on internal hosts

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.

Translations

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.po

Some 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.

Uninstalling

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_version

Deleting 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.