Compatibility Mode

WP Migrate DB Pro Versions 1.8+

As of WP Migrate DB Pro 1.8, compatibility mode was revamped to exclude all plugins and themes by default and to be automatically enabled.

Plugins can be whitelisted to run during migrations by using the plugin selector at the bottom of the “Settings” tab.

Compatibility Mode

There is also a filter available to whitelist plugins. Using the wpmdb_compatibility_plugin_whitelist filter, you can whitelist a plugin by adding it’s name to the whitelisted plugins array:

add_filter( 'wpmdb_compatibility_plugin_whitelist', function ( $plugins ) {
    $plugins[] = 'my-neat-plugin';
    return $plugins;
} );

Adding a plugin this way will always have it enabled during migrations, without the need to use the plugin selector in the WordPress admin.

If for whatever reason, you need to enable a theme to run during a migration, the wpmdb_compatibility_enable_theme hook can be used.

add_filter( 'wpmdb_compatibility_enable_theme', function () {
    return true;
} );

How it Works

A regular WordPress plugin isn’t able to control which plugins are loaded and which aren’t. So what Compatibility Mode does is add an MU plugin when you activate WP Migrate DB Pro.

MU plugins are very different from regular WordPress plugins. They are installed in a special /wp-content/mu-plugins/ folder separate from regular plugins. They are active for as long as they are in that folder. To deactivate them you need to remove them from that folder, or in the case of WP Migrate DB Pro, toggle ‘Plugin Compatibility Mode’ off.

The other thing is that an MU plugin is executed before regular plugins are loaded. This is why we use an MU plugin here. We can get ahead of the loading of regular plugins and control which ones are loaded.

The same is true for themes. By using an MU plugin we’re able to unload a theme’s functions.php file while also suppressing any PHP errors that may crop up during a migration.

It is important to note that we only exclude plugins and themes from loading once we have determined that the request is a migration request from WP Migrate DB Pro. Plugins are never actually disabled throughout this process, they’re simply not loaded.

Plugins that start with wp-migrate-db or wpmdb will always be loaded. This should keep any tweaks plugins you may have installed running.

Serialized Data Errors

WP Migrate DB - Failed to instantiate object for replacement. If the serialized object's class is defined by a plugin, you should enable that plugin for migration requests. 

The above error can sometimes occur if you have a serialized object saved in your database. As outlined in the error message, the fix for this is to whitelist the plugin that is causing the error.

When Compatibility Mode Doesn’t Work

Compatibility Mode works in most cases for most plugins. However, since Compatibility Mode works by intercepting requests for the active_plugins option, any hooks that are fired prior to the query section of the get_option() function will not get intercepted. One such case is the query filter which is fired in wp-includes/wp-db.php before a query is run.

WP Migrate DB Pro Versions 1.4 to 1.7.2

Compatibility mode was introduced in WP Migrate DB Pro version 1.4 and introduces a new setting that allows you to control which WordPress plugins are loaded for requests made by WP Migrate DB Pro. It’s the ability to exclude plugins from loading during a migration request.

Activating compatibility mode will greatly reduce the chance of a another plugin disrupting the migration process. It may also boost the overall speed of the migration and will reduce the migration’s memory footprint by excluding unnecessary plugins.

Activating Compatibility Mode

  1. Log into your WordPress admin area
  2. Go to the WP Migrate DB Pro plugin page (Tools → Migrate DB Pro)
  3. Click the “Settings” tab
  4. Enable the option that reads “Plugin Compatibility Mode”
  5. Read the prompt and click “OK”
  6. Click the “Select All” text link below the text area (see note)
  7. Click the “Save Changes” button

Note: The WP Migrate DB Pro core and addon plugins are automatically excluded from this list to ensure you’re not excluding plugins that are required to execute the migration. You will also want to exclude plugins that affect the migration using filters and/or actions.

For more information on compatibility mode please see our introductory post on it.