WPCOM Legacy Redirector

Simple plugin for handling legacy redirects in a scalable manner.

This is a no-frills plugin (no UI, for example). Data entry needs to be bulk-loaded via wp-cli commands.

Activating the Plugin

WPCOM Legacy Redirector can’t be activated through the Dashboard. Add the following to your theme:

wpcom_vip_load_plugin( 'wpcom-legacy-redirector' );

Adding Redirects

Since the plugin has no UI, we can add redirects via the `wp wpcom-legacy-redirector import-from-csv` command.

The CSV file should consist of the request url (without domain, and including preceding slash), followed by the destination address:


Both relative paths and absolute urls are supported as the destination. This value is passed to wp_safe_redirect() internally, so be sure it’s a valid address.

Note: If redirecting to other domains, we must also whitelist the allowed domains by filtering allowed_redirect_hosts:

add_filter( 'allowed_redirect_hosts', function( $hosts ) {
    $hosts[] = 'my-other-domain.com';
    $hosts[] = 'www.my-other-domain.com';

    return $hosts;

Data Overview

Redirects are stored as a custom post type and use the following fields:

- post_name for the md5 hash of the “from” path or URL.
– we use this column, since it’s indexed and queries are super fast.
– we also use an md5 just to simplify the storage.
– post_title to store the non-md5 version of the “from” path.
– one of either:
– post_parent if we’re redirect to a post; or
– post_excerpt if we’re redirecting to an alternate URL.

CLI Commands

Two options come with the plugin:

- Build redirects from CSV.
– We just need a CSV file with the following mapping structure:
– `redirect_from_path,(redirect_to_post_id|redirect_to_path|redirect_to_url)`
– Build redirect from a meta field.
– Just provide the meta_key for posts where the legacy URLs are stored.

Please contact us before using this plugin to verify your redirect strategy.