Fix Broken Links in WordPress

Learn how to update broken links on your Pantheon WordPress site so that the URL references the correct file path and domain name.


Whether by accident or by virtue of "web rot", links in your content may eventually stop working. This happens when links are placed into your site's code that use an IP address instead of your actual domain name. These links will eventually break when your application container’s IP address changes due to the nature of Pantheon’s cloud-based infrastructure.

Some code relies on $_SERVER['SERVER_NAME'] and $_SERVER['SERVER_PORT'] to construct URLs. This doesn't work well on Pantheon because this environmental data will be for ephemeral container data, which can lead to broken links. For more information, see SERVER_NAME and SERVER_PORT on Pantheon and Modules and Plugins with Known Issues.

There's a Plugin For That

As with most common problems WordPress site owners face, there's a plugin to help. Actually, there are many. If you go to WordPress.org and search for broken link, you'll find over 700 plugins to evaluate. The Broken Link Checker plugin is the most popular and is active on more than 400,000 WordPress sites.

Installation

You can install the plugin from your WordPress dashboard by following these steps:

  1. Click Plugins, then select Add New.
  2. Search for "Broken Link Checker".
  3. Click Install Now, then click Activate.

Using the Plugin

Once you have the plugin installed and activated, you will see a new option within the Tools section of your WordPress dashboard. Notice that there are no reported broken links. Don't get too excited—you won't see any until WordPress runs it's next Cron job. In the background, WordPress will quietly check all your posts, comments, pages, etc., and look for broken URLs. Each URL is queued to be checked so that performance is not negatively affected. Check back later; if you have a lot of content, it will take a while to run.

Broken Link Checker won't keep you from creating bad links, it is simply a reporting tool. You can still do things that are a bad idea, like using the IP address for your site instead of its domain name, but this resource helps you clean things up. The best solution for linking to your own content is to use relative paths. Use /my-cool-blog-post instead of https://example.com/my-cool-blog-post and you never have to worry about portability. For everything else, there is Broken Link Checker.

Update Environment URLs on Pantheon

WordPress stores URLs in various places in the database; considering Pantheon's multi-environment workflow, this can cause unexpected behavior. However, we've integrated the WP-CLI's search & replace functionality into the workflow to assist in updating these URLs. Dashboard DB URL converterPantheon's workflow for WordPress includes an additional feature to update environment URLs automatically. Note that the defaults that are selected when performing a clone operation aren't overridable, as we update the URL to match whatever environment you're cloning to. We do offer the option to convert HTTP to HTTPS and vice versa; in the case you have HTTPS in one environment and not another.

Fix WordPress Content References to the Wrong Domain After Cloning

WordPress sites with custom domains configured on multiple environments may see references to the wrong platform domain after cloning the database from one environment to another.

The Site Dashboard runs wp search-replace during the cloning workflow to update environment URLs automatically. This operation, however, only runs once on a single set of URLs. If the target environment has a custom domain (e.g test.example.com), it's used to replace the source environment's custom domain (e.g. www.example.com). This can cause the target environment to have incorrect references to platform domains (e.g. live-example.pantheonsite.io).

You can resolve this using one of two methods:

Using Terminus, you can run an additional wp search-replace command on the target environment after cloning. Set or replace the variables $site and $env with your site name and the correct environment:

terminus remote:wp $site.$env -- search-replace "://live-example.pantheonsite.io" "://test.example.com" --all-tables --verbose

The following example also converts the URL from HTTP to HTTPS, for situations where you might have HTTPS in one environment and not another:

terminus remote:wp $site.$env -- search-replace "https://live-example.pantheonsite.io" "http://test.example.com" --all-tables --verbose

For those using Quicksilver scripts, consider the following example. On each passthru line, replace example#.pantheonsite.io and example.com with the domains you want to find and replace, respectively:

<?php
echo "Replacing previous environment urls with new environment urls... \n";

if ( ! empty( $_ENV['PANTHEON_ENVIRONMENT'] ) ) {
  switch( $_ENV['PANTHEON_ENVIRONMENT'] ) {
    case 'live':
      passthru('wp search-replace "://test-example.pantheonsite.io" "://example.com" --all-tables ');
      break;
    case 'test':
      passthru('wp search-replace "://example1.pantheonsite.io" "://test-examplesite.pantheonsite.io" --all-tables ');
      passthru('wp search-replace "://example2.pantheonsite.io" "://test-examplesite.pantheonsite.io" --all-tables ');
      passthru('wp search-replace "://example3.pantheonsite.io" "://test-examplesite.pantheonsite.io" --all-tables ');
      break;
  }
}
?>

The example above replaces three URLs when cloning to the test environment with test-examplesite.pantheonsite.io, and replaces that domain with the example custom domain example.com when cloning to the live environment.

You can find this example and many others in the Quicksilver Examples repo.