WPCOM Legacy Redirector

Simple plugin for handling legacy redirects in a scalable manner.

The WPCOM Legacy Redirector is a plugin on WordPress.com VIP that allows you to set up redirects for legacy content on your WordPress.com site in a scalable manner.

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

  • post_name: contains the md5 hash of the “from” path or URL
  • post_title: contains the “from” path or URL (without being hashed)
  • post_parent (if we’re redirecting to another post ID) OR post_excerpt (if we’re redirecting to another URI or absolute URL)

All interaction with this plugin is done via the command line, and all data about redirects needs to be bulk-loaded via wp-cli commands.

Redirect data can be stored in a CSV file OR in a post meta field. With the post meta field method, the resulting redirect is then attached to an existing post (and follows the post through future updates) whereas with the CSV method, the redirect is attached to a hardcoded URL.

If you have questions about how this plugin will work on your site or if you’d like to have us review your redirect strategy, please contact us before using this plugin.

Activating the Plugin

WPCOM Legacy Redirector cannot be activated through your site Dashboard like other plugins. Instead, add the following to your theme’s functions.php file:

wpcom_vip_load_plugin( 'wpcom-legacy-redirector' );

Activating the plugin will make its wp-cli functions available on the command line, but does not otherwise make any changes or create menu items or settings in the Dashboard.

Adding Redirects from Post Meta Fields

You can add redirects from post meta fields using this command:
wp wpcom-legacy-redirector import-from-csv --meta_key=my-post-meta-key

The plugin will search for all posts that have a post meta field named “my-post-meta-key” (or whatever key name you decide to use) and create a redirect from the address found in the meta field to the post that has that meta field. The meta field can contain relative or absolute URLs, but we recommend specifying absolute URLs where possible.

So, for example, if you wanted to redirect all requests to “http://old-domain.com/old/legacy/path/” to post ID 5, you would set the value of the post meta field named “my-post-meta-key” to “http://old-domain.com/old/legacy/path/” on the post with ID 5.

If you only want to process a certain number of posts at a time, you can add these optional command line parameters:

[--start=start-offset] [--end=end-offset]

where, for example, start-offset might be “1” and end-offset might be “1000”.

Adding Redirects from a CSV File

You can add redirects from a CSV file using this command:
wp wpcom-legacy-redirector import-from-csv --csv=/tmp/my_redirects.csv

The CSV file (in this example, /tmp/my_redirects.csv) should consist of the from url (without domain, and including preceding slash), followed by the destination address:

/old/legacy/path,/shiny/new/path
/another-legacy-path,http://my-other-domain.com/other-path

The plugin will create a redirect from each source/legacy path to the destination address specified.

Destination Addresses

The destination address in the CSV import method can be one of: a Post ID, a relative path, or an absolute URL.

The destination value is passed to wp_safe_redirect internally, so be sure it’s a valid local address. If you want to redirect to other external domains, you can whitelist that domain by filtering allowed_redirect_hosts in your theme:


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

    return $hosts;
});

Testing and Production Runs

Before creating redirects on your production WordPress.com site, please test out the legacy redirect import process in your development environment to ensure the redirects are created as expected.

Once you’ve verified that the process works as expected, you can request a run of the redirector import command of your choosing by opening a new support ticket with WordPress.com VIP. Please make sure to include:

  • the URL of the site where you want to run the import
  • the CSV file containing your redirects (if using the CSV import method)
  • the name of the meta key containing your redirect destinations (if using the post meta import method)
  • Confirmation that you’ve run the import as a test in a development environment
  • An example URL on your site that is not currently redirected, and where it should redirect to when the import is complete (for testing)
  • Your desired timing for when the redirects are created

Once we receive your support request with all of the above information and have resolved any questions, we will proceed with running the import command.

Frequently Asked Questions

Q: Shouldn’t I just use the Safe Redirect Manager for redirects?
A: The Safe Redirect Manager allows you to create and update up to 300 redirects via your Dashboard. Above that number the redirect management becomes too slow for optimal performance, and so for redirect creation above that amount, you should use this plugin.

Q: Can I create redirects for only a certain post type? 
A: At this time, the redirector plugin operates on all post types. But, in the case of adding redirects from post meta fields, it will only create redirects where it detects the existence of the specified meta key.

Q: Are there performance implications when running the import on a production site?
A: When we create a redirect for an existing URL, we clear the cache of any content that existed at that address. Importing thousands of redirects can temporarily decrease the performance of your site while that caching is cleared and then rebuilt. In general, creating redirects has a small performance impact on your site but

Q: Will the redirector automatically detect “from” URLs with and without trailing slashes?
A: No – you will need to add a redirect for each version of a “from” URL that you want to redirect, e.g. one with and one without a trailing slash.

Q: Will the redirector handle domains/URLs not mapped to my WordPress.com site?
A: The redirector can only handle “from” URLs that use one of the domains mapped to your WordPress.com site. If you want to set up redirects on domains hosted elsewhere, that would be configured where those domains are hosted. Alternatively, you can point and map the domain to your WordPress.com site and then set up redirects for it.

Q: Can I use the plugin to dynamically create redirects (e.g. for a custom promotional URLs, link shortening, etc)?
A: Yes. The plugin has a basic API with two functions you can use: WPCOM_Legacy_Redirector::insert_legacy_redirect( $from_url, $redirect_to ) and WPCOM_Legacy_Redirector::get_redirect_post_id( $id ).