Fix Broken Links in WordPress
Learn how to update broken links on your Pantheon WordPress site.
This section provides information on how to correct broken links so that the URL references the correct file path and domain name.
Update Links Referencing IP:Port
Links in your content may stop working by accident or due to web rot. This happens when links placed in your site's code 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.
Links Constructed Using SERVER_NAME or SERVER_PORT
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 is for temporary container data, which can lead to broken links. Refer to SERVER_NAME and SERVER_PORT on Pantheon and WordPress Plugins and Themes with Known Issues for more information.
Available Plugins
There are a number of plugins that can help you correct and maintain your links. Visit WordPress.org and search for broken links for a comprehensive list of plugins. The Broken Link Checker plugin is the most popular and is active on more than 400,000 WordPress sites.
Install Broken Link Checker
You can install the Broken Link Checker plugin from your WordPress dashboard by following these steps:
Set your Connection Mode to SFTP.
Click Plugins, then select Add New.
Search for
Broken Link Checker.Click Install Now, then click Activate.
Use the Plugin
You will see a new option within the Tools section of your WordPress dashboard when the Broken Link Checker plugin is installed and activated. Notice that there are no reported broken links. This is normal as broken links aren't identified until WordPress runs it's next Cron job. WordPress checks all your posts, comments, pages, etc., in the background and look for broken URLs. Each URL is queued to be checked so that performance is not negatively affected.
Broken Link Checker is a reporting tool and won't keep you from creating bad links. 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 to avoid portability problems.
Update Environment URLs on Pantheon
WordPress stores URLs in various places in the database. This can cause unexpected behavior due to Pantheon's multi-environment workflow. WP-CLI's search and replace functionality is integrated into the workflow to assist in updating URLs.
Pantheon's workflow for WordPress includes an additional feature to update environment URLs automatically. Note that you can't override the defaults that are selected when performing a clone operation when you update the URL to match whatever environment you're cloning to. You can convert HTTP to HTTPS and vice versa if this varies among your environments.
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 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 several methods:
There are several plugins with search and replace functionality. WP Migrate DB, for example, works well on our platform.
Make sure you select the Find & Replace functionality:
Another popular search-replace plugin is Better Search Replace. However, there is an additional filter that must be added for it to work on Live, as outlined in Plugins and Themes with Known Issues.
You can use Terminus to 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 --dry-runThe 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 "http://live-example.pantheonsite.io" "https://test.example.com" --all-tables --verbose --dry-runNote: The example code above includes --dry-run, which executes the command but prevents permanent changes. Remove this flag when you are confident that the values are correct.
Consider the following example if you are using Quicksilver scripts.
Replace example#.pantheonsite.io and example.com with the domains you want to find and replace on each passthru line:
<?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.
In addition to the example above, URLs may be stored in an encoded format. If the example above fails to resolve all issues, search for patterns like %3A%2F%2Fexample.com and :\/\/example.com.