Quick Tip: Preventing WordPress Plugin Incompatibilities

With WordPress taking over more than 25% of the web, developers need to be able to prepare their plugin for maximum compatibility. According to the latest statistics, WordPress can be installed on six different PHP versions with no guarantee that the user who is running the site, is using the latest version of WordPress.

There are still people who run WordPress version 3.0 according to the statistics.

If we’re also depending on the third party libraries, we’ll need to consider the requirements of these libraries as well. The same applies to PHP extensions if they’re being used.

Detecting Incompatibilities at Plugin Activation

By taking a defensive approach in plugin activation, we can be sure that our plugin is never installed on incompatible environments.

Some other benefits include:

• Reduce end users’ frustration when our plugin doesn’t work.
• Increase the guarantee that our plugin is installed on the most compatible environments.
• Encourage the site owners to upgrade their site.
• By intercepting the problem early, we can offer an alternative to the users, or redirect them to a preferred support channel.

Basic Concept

In order to do this correctly, there are a few things that need to be done:

• First, we need to create a function that checks the environments to make sure that all requirements are met.
• If the requirements are not satisfied, show the admin notice on the dashboard and disable the plugin.
• If the requirements pass, we will proceed with the rest of our plugin code.

Let’s work our code based on the established flow above.

Checking If the Requirements Are Met

First, we will create a function that will check the environments against our requirements that will return either true or false. In this function, we are free to check for anything that we want, whether that is the WordPress version, PHP version or anything else that is needed to ensure our plugin can run smoothly. Let’s start with simple requirements that need at least WordPress 4.0 as well as PHP 5.3. To add a bit of complexity, we will also need ftp PHP extension to be activated.

function prefix_is_requirements_met() {
    $min_wp  = '4.0';
    $min_php = '5.3';
    $exts    = array('ftp');

    // Check for WordPress version
    if ( version_compare( get_bloginfo('version'), $min_wp, '<' ) ) {
        return false;
    }

    // Check the PHP version
    if ( version_compare( PHP_VERSION, $min_php, '<' ) ) {
        return false;
    }

    // Check PHP loaded extensions
    foreach ( $exts as $ext ) {
        if ( ! extension_loaded( $ext ) ) {
            return false;
        }
    }

    return true;
}

For our purpose, a simple version_compare and extension_loaded is suffice but feel free to extend the function to suit any extra requirements that need to be met.

Disable the Plugin and Show Activation Failure Notice

We then can run this function in our plugin main file, and if the requirements are not met, we will then add two callback functions, to each of admin_init and admin_notices respectively.

if ( ! prefix_is_requirements_met() ) {
    add_action( 'admin_init', 'prefix_disable_plugin' );
    add_action( 'admin_notices', 'prefix_show_notice' );
}

Let’s see what each of the callback functions do.

function prefix_disable_plugin() {
    if ( current_user_can('activate_plugins') && is_plugin_active( plugin_basename( __FILE__ ) ) ) {
        deactivate_plugins( plugin_basename( __FILE__ ) );

        // Hide the default "Plugin activated" notice
        if ( isset( $_GET['activate'] ) ) {
            unset( $_GET['activate'] );
        }
    }
}

Before we can safely call the deactivate_plugins function, we verify the permission of the current logged in user, as well as checking if the plugin is active. This is to handle some edge cases, where the plugin might be already active before for some reason such as during a plugin update. Note that we further unset the $_GET['activate'] variable, otherwise, the ‘Plugin activated’ notice will still be shown even though the plugin is not activated. This is to prevent any confusion for end users.

To display the notice of activation failure is fairly straightforward, all we need to do is to follow the original markup that WordPress uses to show the notices.

function prefix_show_notice() {
    echo '<div class="error"><p><strong>Plugin Name</strong> cannot be activated due to incompatible environment.</p></div>';
}

Conditionally Loading the Rest of the Plugin’s Code

For this, just include the else statement in our previous code block where we do the checking. So the final version of the code will be:

if ( ! prefix_is_requirements_met() ) {
    add_action( 'admin_init', 'prefix_disable_plugin' );
    add_action( 'admin_notices', 'prefix_show_notice' );
} else {
    // The rest of plugin's code
}

With that done, we can test to see if the code really works. Just change the value for the minimum required value of WordPress or the PHP version to a value that will fail, and activate the plugin. We should be able to see the custom notice as well as the plugin being deactivated properly.

Conclusion

With a few lines of boilerplate code, we can reduce the risk of our plugin being activated on incompatible environments. This will not only help reduce end users frustration, but will also allow us to be sure that our plugin is activated in the best environment possible.