Redirecting Old URLs in WordPress

We recently devised a system to redirect old URLs in PHP so that you could avoid “page not found” errors (I suggest you read it before venturing further). In this article, we’ll create a similar system for WordPress, the popular PHP CMS.

How is WordPress different?

WordPress routes all requests through a single index.php file. Under normal circumstances, all URLs that don’t map to a physical file or folder on your server will be handled by WordPress. This includes all invalid addresses, so there’s no need to configure a 404 error document in Apache or IIS.

There’s probably no need to worry about redirecting old URLs if you’ve been using WordPress since day one. The system is reasonably good at finding the right page, even if you change your permalink structure (Settings > Permalinks). However, if you’re migrating content from a static site or another CMS, you’ll almost certainly have URL mismatches.

Updating the theme

We’re going to handle redirects within your WordPress theme. You could create a plugin, but:

• the redirects are site-specific and a generic plugin would add more complexity
• the code is unlikely to require further updates and it’s preferable to avoid having users configure or disable it, and
• embedding it within the theme makes it more portable–you just copy theme files to the server

First, locate your theme files in wp-content/themes/my-theme-name. Many themes provide a 404.php file to handle “page not found” errors, but you can create one if necessary; for example:

<?php get_header(); ?>

<h1>Page not found</h1>
<p>Sorry, we cannot find that page.</p>
<p>Please browse the sitemap&hellip;</p>

<ul id="sitemap">
<?php wp_list_pages('title_li='); ?>
</ul>

<?php get_footer(); ?>

You should now include redirect.php at the top of the 404.php file, for example:

<?php include('redirect.php'); ?>
<?php get_header(); // etc...

(Note that earlier versions of WordPress may require: include(TEMPLATEPATH.'/redirect.php'); –that’ll work in the latest versions too.)

Now create the redirect.php file in your theme folder and add the following code:

<?php
// current address
$oldurl = strtolower($_SERVER['REQUEST_URI']);

// new redirect address
$newurl = '';

// old to new URL map (for you to configure)
$redir = array(

	'index.html' => '/',
	'article1.html' => '/blogs/my-first-article',
	'article2.html' => '/blogs/my-second-article'

);

while ((list($old, $new) = each($redir)) && !$newurl) {
	if (strpos($oldurl, $old) !== false) $newurl = $new;
}

// redirect
if ($newurl != '') {

	header('HTTP/1.1 301 Moved Permanently');
	header("Location: $newurl");
	exit();

}
?>

The $redir URL mapping array can be configured as necessary. Alternatively, you could use a series of regular expression replacements or a database table lookup to find a valid $newurl.

I hope that helps with your WordPress URL woes. If you have other tips for managing redirects, please leave your comments below.

Frequently Asked Questions about Redirecting Old URLs in WordPress