WordPress Search and Replace

Running a search and replace can be crucial to creating or correcting a WordPress® website.¹

WP Engine automatically runs a search and replace command for you in the processes where one is required, such as updating domains, copying an environment or restoring a backup.

However, if you need to run a search and replace manually, the following options are available:

• Better Search and Replace plugin: This is a great option for less technical users. It has a clean user interface, as well as simple options for free users. It also has a Pro version that offers a greater variety of options.
• WP CLI: For more technical users, WP CLI can be used (included at no cost with SSH Gateway access), which gives more granular control over the process.

In this article, we will explain what happens during the automated search and replace process, as well as how to manually perform a search and replace.

---

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. This process updates the database only, and will not modify instances of the domain located in other files. The domain used in the search and replace is the value located in the site’s WordPress settings.

• Set domain as Primary
• Copy Site
• Copying a multisite network
• “Create from existing” when adding a new environment
• Restore a backup to a different environment (A search and replace is not necessary when restoring to the same environment.)
• Set domain as primary with Domain Connect

Note that a search and replace will be run automatically when adding a new Primary domain to the User Portal and going live.

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

When WP Engine runs a search and replace as part of a larger process, the following steps occur:

1. Determine the domain for both the source and target 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

---

Better Search and Replace Plugin

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, like Better Search and Replace. After installing the plugin, fill in the “Search for” and “Replace with” values, then select the database tables to update (use ctrl + click to select multiple), finally choose any additional settings and click “Run Search/Replace”.

Learn more about Better Search and Replace here.

---

Search and Replace with WP CLI

WP CLI is considerably more flexible than a plugin, as a plugin is simply leveraging 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 new restore 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 target.
• 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

---

NEXT STEP: Learn how to identify and correct mixed content