Find & Replace Fields

The Find & Replace fields are available during any push or pull migration, or when running the Find & Replace tool.

During a migration, you are presented with two standard find and replace fields. These are essential in replacing strings that reference the source website with references to the destination website.

The two standard find and replace fields are:

• Site URL: any URLs referencing the old site will be replaced by the new URL during the migration.
• Root file path: any root file paths referencing the old site will be replaced by the new root file path during the migration.

The site URL find and replace field is absolutely essential as it changes the siteurl and home values in the wp_options table. These values must be updated during a migration to the correct value to ensure that your website loads correctly.

The root file path find and replace is mostly for third-party plugins that store the website’s root file path in the database. This find and replace field will ensure that these values are updated to the correct root file path during the migration.

The site URL and root file path text inputs are filled in for you automatically when performing a pull or push migration. If performing an export migration you will need to fill in these inputs manually.

Retrieving the “New URL” and “New file path” information

WP Migrate DB Pro should be installed and active on both the local and remote WordPress installations.

You can use the following method to retrieve the “New URL” and “New file path” information:

1. Log in to the remote site
2. Navigate to WP Migrate DB Pro plugin page (Tools → Migrate DB Pro)
3. Click the Migrate tab and then click Find & Replace
4. Copy the contents of the first field under the “Custom Find & Replace” header (remote URL)
5. Switch back to your local site
6. Navigate to WP Migrate DB Pro plugin page (Tools → Migrate DB Pro)
7. Click the Migrate tab and then click Find & Replace
8. Paste the contents of your clipboard into the first empty field under “Replace”
9. Switch back to the site you logged into during step 1
10. Copy the contents of the second field under the “Custom Find & Replace” header (remote file path)
11. Switch back to your local site
12. Paste the contents of your clipboard into the second empty field under “Replace”

Custom Find & Replace Fields

Occasionally you might need to specify a custom find and replace field. When doing a push or pull migration, WP Migrate DB Pro will automatically make an additional Custom Find & Replace field available. You can leave this empty, or add a custom find and replace field. If you need more than one custom replacement, you can click the Add Row button below the existing custom find and replace to create a new one.

A prime example of why you’d want to define additional find and replaces is if you have references to your site’s URL in your database that slightly differ in format from your main site’s URL.

Consider the following:

Your website’s URL is: http://hellfish.media

Your default replace will match your site’s protocol-relative URL. If you have references to your site using a sub-domain, these URLs will not be replaced during a migration using the default find and replace fields.

So in this example, http://www.hellfish.media will not be replaced during a migration.

To have those values replaced during the migration you’ll need to add additional find and replace fields to have those slightly different URLs replaced.

For example:

• Find for //www.hellfish.media and replace with //hellfish.media

Regular Expression Find and Replace

There are some situations where you need to find and replace data based on a complex set of conditions rather than just a simple string. As an example, let’s say you need to replace a specific shortcode (foo) with a different shortcode (bar) through all the content on a site while retaining the shortcode’s id attribute.

[foo id="1"]

If you run a custom find and replace to replace the term foo, you’d run into a problem where you would affect any data that uses this string (food, foot, etc). You could try using [foo but that might affect any other shortcodes starting with that same string.

This is where a regular expression find and replace comes into play.

Using the same functionality as the PHP preg_replace function, WP Migrate DB Pro allows you to specify a regular expression (regex) string, to find and replace the correct data.

Your regular expression must be a full pattern regex, meaning it must contain all delimiters and modifiers you wish to use. It’s also worth noting that there is only a specific list of modifiers available to the preg_replace function, as detailed in the Regex Pattern Modifers in the PHP manual.

In the above example, your regex would look something like this:

/\[foo id="([0-9]+)"/

The replace string would look like this, where bar is what we want to replace foo with, and $1 is the data from the capturing group in the original regex, in this case, the id value:

[bar id="$1"

In order to run this on your data, either add this as a custom find and replace row during any migration, or use the “Find and Replace” tool on the site where you want to replace the data.

Enable the regex functionality by clicking on the Regular Expression button, next to the find and replace fields.

Then enter the regex in the find field, and your replacement string in the replace field. If your regular expression is invalid, the plugin will display a notification warning, and you will not be able to run the migration/replacement.

Once you fix the regex, the find and replace row will be ready to be run.

You can test your regex using a tool like regex101.com. When you copy the valid regex from this tool, you must exclude any modifiers not listed in the Regex Pattern Modifers. For example, a new regex on regex101.com includes the g modifier, which means “find all matches rather than stopping after the first match.”. The preg_replace function assumes that it should be replaced globally, so adding that modifier results in an error. It should be left out of your regex in the find field, and the plugin will report it as an invalid regex if you leave it in.

Case-Sensitive Find and Replace

Similar to the regex find and replace, it is also possible to enable a case-sensitive custom find and replace.

The default functionality for custom find and replace is to perform case-insensitive searches. This means that if you enter User in the find field, it would find and replace instances of both User and user. This is not ideal if you only want to replace instances of User!

To enable a case-sensitive custom find and replace, click on the Case Sensitive button next to the find and replace row. Then enter the find and replace strings as normal.

The Find & Replace Tool

The Find & Replace tool is available should you merely need to find and replace data in the current database. This could be something you need to do on a production, staging, or local development version of the site. To access the Find & Replace tool, navigate to Migrate > Find & Replace.

The Find & Replace tool displays one custom empty find and replace field, but you can add as many as needed. You are also able to configure case-sensitive or regex find and replace fields using the tool.

By default, the Find & Replace tool allows you to preview the find and replace operation to ensure you are updating the correct data. When you are ready to run the preview, click the Preview Changes button, which brings up the “Find & Replace (Preview)” modal. This will scan all your tables for the data to find, and display the number of matches found in each table.

You can click on a set of matches for a table to view a diff of the data that will be changed. Click Back to all tables to return to the preview.

If you are happy with the changes, click Apply Changes to run the find and replace operation or Cancel to tweak your find and replace fields.

Alternatively, if you are ready to run the find and replace operation without previewing the changes, expand the Preview Changes split button menu by clicking on the chevron to the right of the button, and select Find & Replace. This will automatically run the find and replace operation.

When saving a Find & Replace profile, the selected behavior (either “Preview Changes” or “Find & Replace”) will be saved with the profile.