Using WP_SITEURL and WP_HOME to migrate a WordPress site

If you have migrated a WordPress site before you will be familiar with the WordPress Constants, WP_HOME and WP_SITEURL. These constants are the first solution mentioned on the migration guide on Codex.

These values determine how WordPress builds paths of your site. From theme assets paths to login pages, all depend on these values.

Using these constants correctly can give you a very smooth migration. But use them incorrectly and your site will be hosed. You could even lock yourself out of wp-admin with a very bad combination. Or break your site’s theme with 404 errors.

Home URL

The WP_HOME constant corresponds to the WordPress Address (URL) input field in the Admin. It is used to determine the result of the home_url API function.

The Home URL is the URL you want your visitors to enter to reach your blog. If you wish to have a blog at /musings, then the WP_HOME should be http://mysite.com/musings.

Site URL

The WP_SITEURL constant corresponds to the Site Address (URL) input field in the Admin. And it is used to determine the result of the site_url API function.

The Site URL must point to the path to your WordPress installation. If you have installed WordPress in a subdirectory like /wordpress then this path must be http://mysite.com/wordpress.

Locked Out of WP-Admin

These constants can easily lock you out of the WordPress admin. If you installed WordPress in the root of your site but want to move it to /blog instead. And if you use the incorrect configuration,

define('WP_HOME', 'http://mysite.com/blog');
define('WP_SITEURL', 'http://mysite.com/blog');

You will no longer have access to the Admin from /wp-admin. The login form will redirect to /blog/wp-login.php which doesn’t exist.

404_site_url

Visiting /wp-login.php directly shows a login form that is unstyled. And it submits the POST to the incorrect /blog/wp-login.php page.

How Javascript & CSS Paths break

Another common way these constants break your site is when the WP_SITEURL is not configured correctly. For instance if WordPress core files are in a subdirectory like wordpress, and you want to point the WordPress blog to /musings. You could have the incorrect configuration,

define('WP_HOME', 'http://mysite.com/musings');
define('WP_SITEURL', 'http://mysite.com/');

This configuration will break links to all your theme’s CSS and Javascript files.

404_site_url

The site’s Javascript & CSS files are now 404s pointing to paths at /wp-content/.... But the files are actually located at /wordpress/wp-content/....

Changing WP_CONTENT_URL to http://mysite.com/wordpress/wp-content might seem like a quick fix. But it won’t resolve the problem completely.

Some Javascript files like jQuery are served from the /wp-includes directory. Those paths also need to point to /wordpress/wp-includes.

You could fix this with some Rewrite Rules but it’s easiest to ensure that WP_SITEURL points to where the WordPress files are. This is the path to which you add /wp-admin to login to the WordPress Admin.

Additional Caveats

Another thing to note about these constants is that they are generally used with their corresponding API functions home_url and site_url. These functions run through filter hooks option_home and option_siteurl respectively.

Thus the final values of these functions may depend on plugins that you have installed. Multisite even removes these filters to ensure that these constants are ignored.

Conclusion

When you don’t specify these constants their values come from options stored in the database. And when present the database options are overridden and you can’t edit them through the Admin.

These options are a little fragile and loosing the flexibility of changing them in the Admin is better than dealing with a broken site.

The Codex guide states that use of these constants is akin to hardcoding and is not the best fix. But if you use them correctly they can provide a simpler solution when migrating a site.

Make sure that WP_SITEURL is pointing to where WordPress lives and you will avoid mucking about in the database to fix these paths.

Level Up your WordPress-Fu with Weekly Tips in your inbox. Find out just why query_posts() is evil and why you should stop using it. (No Spam)

  • RyonWallace

    The “Migration Guide” link you refer to is actually somewhat misleading. For a slightly clearer picture, read the “Changing Your Domain Name and URLs” section on this page: http://codex.wordpress.org/Moving_WordPress .

    Unfortunately this process is not as easy as modifying the values of WP_HOME and WP_SITEURL. Changing these constants will “fix” your admin and navigation links, but image URLs, etc will still point to the previous paths that remain in the database. And since many of these links are serialized, you cannot rely on a simple search-and-replace.

    I’d recommend using a search-and-replace tool which takes serialized data into account (there are several), or the Duplicator plugin.