WordPress Search and Replace

Running search and replaces is crucial to successfully running a website. Below we’ll cover when and how you can use a search and replace, and when one might be automatically run for you.

---

Terminology

We’ll use the following terms throughout this article:

• Source – this is the original environment that you are copying from
• Target – this is the destination of the copy or deploy

The target import will be replaced with your source input.

---

Search and Replace Plugins

Whether you are looking to correct mixed content, or simply need to update hard-coded references of your domain after taking a site live, running a search and replace is a common practice when managing a website.

The easiest way to perform a search and replace on your own is with a plugin. Some recommended plugin options include:

• Better Search and Replace
• Search & Replace

---

Search and Replace with WP CLI

WP CLI is considerably more flexible than a plugin, as a plugin is simply leveraging parts of WP CLI in the first place, however it comes with its own set of risks. Be sure to first run any command using the --dry-run flag to preview the changes before executing them and always make a checkpoint first.

See our guide to learn how to connect to SSH Gateway.

The basic structure of a WP CLI search and replace looks like this:

wp search-replace 'source' 'target'

Where source is the phrase you’re searching for, and target is the phrase you’re replacing with. Be sure to leave the single quotes around the phrase to ensure only the correct content is found and updated.

If you want to run a search-replace only on specific tables, you can add them in like this:

wp search-replace 'source' 'target' wp_posts wp_options

For more information on how to use a WP CLI search and replace, check out the WordPress developer’s guide.

Search-Replace Flags

Flags are extremely important to a search and replace to help ensure you’re getting the intended result. Add as many flags, separated by a space, as-needed to achieve the desired result.

wp search replace 'olddomain.com' 'newdomain.com' --precise --skip-columns=guid,user_email --skip-plugins --skip-themes --report-changed-only --dry-run

--precise – Force the use of PHP (instead of SQL) which is more thorough, but can be slower. This will also ensure serialized data is search/replaced. While it is slower, it is more effective and recommended to always use this flag.

--dry-run – Preview the command, but do not execute it. It is always recommended to run the command first with this flag. If you’re happy with the output, run the command again without it to actually perform the replacements.

--network – On a multisite, enable replacement on all subsites in the database. Without this flag, the command is run only on the selected subsite’s tables.

--all-tables – Enable replacement on ALL tables in the database, regardless of the prefix, and even if not registered on $wpdb. Overrides --network.

--skip-columns=guid,user_email – Skips the guid column, which is used primarily for feeds. The GUID must never change, even if you shift domains around. Skips the user_email column which will prevent email addresses from inadvertently being updated.

--report-changed-only – Results only display the tables that have changes available. This is helpful when working with large databases or multisites.

--skip-plugins and --skip-themes – Prevents plugin or theme code from rendering when WP CLI commands are run. If your site is returning an error when running commands, use this.

--regex – Runs the search using a regular expression (without delimiters). Warning: search-replace will take about 15-20x longer.

Search-Replace Examples

Search for your old domain, and replace with your new domain:

• Be sure to update the values in bold to your own
• Uses PHP, preserves emails and GUIDs
• Will not execute any code, only preview results. To execute live, remove --dry-run

wp search-replace 'olddomain.com' 'newdomain.com' --precise --skip-columns=guid,user_email --skip-plugins --skip-themes --report-changed-only --dry-run

Search and replace to correct mixed content:

• Similar to the command above, this command also includes protocol and will change it from http to https to resolve mixed content.
• Be sure to replace domain.com with your domain in the source and destination.
• Will not execute any code, only preview result. To execute live, remove --dry-run

wp search-replace 'http://domain.com' 'https://domain.com' --precise --skip-columns=guid,user_email --skip-plugins --skip-themes --report-changed-only --dry-run

---

Automated Search and Replace

Moving a WordPress installation between different environments can be a pain. That’s why WP Engine has created tools to help you copy and deploy your WordPress sites between WP Engine installs. When you interact with an environment on WP Engine using the following of our tools, we will automatically handle the domain search and replace process for you:

• Copy Site
• Legacy Staging push
• “Create from existing” when adding a new environment
• Restore a backup to a different environment
• Set domain as primary with Domain Connect

These search and replaces are performed using WP CLI and are protocol-less (http/https), case-insensitive and include serialized data.

The process also supports URL cases such as new/long TLDs (.solutions), punycode TLDs (test.XN--VERMGENSBERATUNG-PWB), and second level TLDs (test.co.uk).

Lastly, our cases include adjustments to account for the following characters which may come before or after a domain URL:

• Blank spaces
• New lines
• Brackets [ ]
• Parenthesis ( )
• Curly Brackets { }
• Angle brackets < >

Automated Search and Replace Process

1. Determine the domain for both the source and destination environments
2. Verify Core Checksums
   • Modifying WordPress core is not permitted on the WP Engine platform
3. Perform the following domain search and replaces:
   • source.com -> target.com
   • www.source.com -> www.target.com
   • subdomain.source.com -> subdomain.target.com
   • source.com/path -> target.com/path
   • <a href=”source.com”>source.com</a> -> <a href=”target.com”>target.com</a>
   • /wp-content/www.source_.com_.png -> /wp-content/www.source_.com_.png
4. Purge server caches
5. Reset the website’s file permissions

---

NEXT STEP: Learn how to identify and correct mixed content