WordPress Plugin Updates the Right Way

Detailed explanation and best practices of WordPress plug-in update mechanism

WordPress itself does not provide a native plug-in update process, and developers need to implement it themselves. This includes updating the version number in the database and creating new options if necessary.

The version number of the WordPress plugin should be stored in two places: constants in the plugin main file and options in the database. This enables detection whether the database options have been updated since the last plugin update.

When updating options, developers should be careful not to overwrite user's choices. If an option does not exist in the database, it should be created; if it already exists, it should not be overwritten.

For options stored as arrays, developers can use the PHP function array_merge() to ensure that all keys are defined and no non-existent options are introduced. This also ensures that if the user changes the old option, its value will be retained.

A few weeks ago, I received an email about WP Photo Sphere (a WordPress plugin I developed). The problem is big: Updating the plugin causes some installers to crash. After some investigation, I found that the problem stems from the options used by the plugin: these installers don't provide any default values ​​for the new options I added.

These values ​​are very important, so I need a way to create the default values. However, contrary to what I think, WordPress does not provide any native methods to handle the update process.

This is why I want to write this tutorial. First, we will understand exactly why we need the update process and why WordPress does not provide such process. I'll then show you how to properly create your own process to update your options.

The importance of plug-in update process

Usually, changing the file is not enough to correctly update something. For example, when you manually update your WordPress file to a new version, the platform will ask you to click a button to update the database.

Suppose you use options in the plugin. As the plugin evolves, you will need more options in the new version. It's easy to create new options when the user first activates the plugin, you just need to use the activation hook.

For example, let's look at the following code:

function my_awesome_plugin_activation() {
    update_option('my_awesome_plugin_option', 'default value');
}
register_activation_hook(__FILE__, 'my_awesome_plugin_activation');

If you are not familiar with using update_option() instead of add_option(), please don't worry, we will explain it later when discussing how to deal with the update process.

If you want a new option, or if you update the value of an existing option in a new version, you need to update the user database that already uses your plugin, so we need a function that is called immediately after the update .

Activating the hook can be a bit confusing. After all, when you automatically update the plugin, it gets deactivated and reactivated, so we can expect this hook to be called. But that's not the case.

More precisely, it used to be, but WordPress stopped this behavior in version 3.1. The development team explained this option and you can read the full explanation on the Make WordPress Core blog. The main reason is that it is not called every time, because if the user manually updates the plugin, the activation hook can be skipped.

Therefore, WordPress does not provide a default method to automatically call functions after plug-in updates. That's why you need to build your own process.

How to deal with the update process

In this part of this tutorial, I will show you how to automatically call a given function after the plugin is updated. We will see in the next section how to properly handle the update of existing options and the creation of new options (in the same function).

Principle of this method

The global principle of our method is that we store the version number of the plugin in two places: constants in the plugin main file and options in the database.

The numbers in the database will store the user's currently installed version, while the numbers in the constant are the current version. If these two numbers are different, the database options have not been updated since the last plugin update, so we need to do this.

In this case, we will call a function that updates all necessary options. This function also updates the version number stored in the database: so that we do not over-call this function.

Constant

Now that we have covered what we are going to do, it’s time to write code! First, add a constant definition in the plugin main file and take your current version number as the value. To prevent any problems, we test whether it has not existed yet.

function my_awesome_plugin_activation() {
    update_option('my_awesome_plugin_option', 'default value');
}
register_activation_hook(__FILE__, 'my_awesome_plugin_activation');

Usually, the plugin version uses a digital identity, but feel free to use it if you use a different system. The only constraint here is to provide a unique identifier for each version or at least for each version that needs to change the database (new options, new defaults, etc.).

Check function

We now need to write a function to check if the database needs to be updated. This function compares the previously defined constants with the values ​​currently stored in the database. To do this, we will make sure our function is called anywhere, using the plugins_loaded action, which will be triggered once all plugins are loaded.

if (!defined('MY_AWESOME_PLUGIN_VERSION'))
    define('MY_AWESOME_PLUGIN_VERSION', '3.4.1');

This function will be simple. We retrieve the version number stored in the database, just like any other option, and compare it to the constant. If these values ​​are different, we will call the my_awesome_plugin_activation() function.

function my_awesome_plugin_check_version() {
}

add_action('plugins_loaded', 'my_awesome_plugin_check_version');

Now, we need to clarify some issues. First, what if the option does not exist in the database yet? If the option does not exist, get_option() will return false, which is different from your version number, so the function will be called.

So why do we call the activation function? To be clear, we can create a new function that is specifically used for the update process. However, if you do this, you will see that this new function will be very similar to activation, as updating options can be the same as creating options.

Update the version number in the database

You can do whatever you want in the activation function called above. However, one thing is necessary, and that is to update the version number stored in the database. This way, we don't call our functions every time the page is loaded.

function my_awesome_plugin_activation() {
    update_option('my_awesome_plugin_option', 'default value');
}
register_activation_hook(__FILE__, 'my_awesome_plugin_activation');

Please note the trick: We do not use add_option(), only use update_option(). In fact, if the option does not exist yet, update_option() will create it. If it exists, it will update its value to the indicated value. This is why we can use our activation function as an update function without any problem.

Update options

Don't overwrite user's choices!

Updating any option is the same way we update the version number: you can call update_option() and it's done, even if this is the first time WordPress has seen the option.

However, we don't always want to update the option values. In fact, if you use options, it is usually to make your users personalize the settings. By using update_option(), you will overwrite the user's choices every time you update the plugin, which is not what we want to do.

Above, we see that if the option does not exist, get_option() will return false. We will use this behavior to test if the option we want to update exists in the database. If this is the case, we do nothing. Otherwise, we create this option.

if (!defined('MY_AWESOME_PLUGIN_VERSION'))
    define('MY_AWESOME_PLUGIN_VERSION', '3.4.1');

Please note that this test is necessary for options we do not want to override. In some cases we might want to do this, considering the version number, we certainly don't want to keep the old value!

Special case—array

You should know that WordPress allows arrays to store the values ​​of our options, and creating them is no more difficult than creating other options. For example:

function my_awesome_plugin_check_version() {
}

add_action('plugins_loaded', 'my_awesome_plugin_check_version');

If you need multiple settings, using arrays is a good idea. This way, you don't use a lot of entries in the database, and you limit the chances of another plugin using options with the same name. However, this can cause problems when we consider the update process.

To understand the reasons, let's say you have an array as an option with some keys. Your users will surely personalize these values. Using the tests we did above, we can only create the option if it does not exist and these choices are not overwritten. This looks simple, but what if you want to create a new key in an array?

If the option exists in the database, the previous code will not create it, so your new key will not exist. However, if we delete the condition, the array will retrieve its default value every time a new update. Not ideal. Fortunately, there is a solution!

First, we define an array containing the default values ​​of the options (if a new key exists).

if (MY_AWESOME_PLUGIN_VERSION !== get_option('my_awesome_plugin_version'))
    my_awesome_plugin_activation();

Then, we retrieve the array currently stored in the database.

function my_awesome_plugin_activation() {
    update_option('my_awesome_plugin_option', 'default value');
}
register_activation_hook(__FILE__, 'my_awesome_plugin_activation');

Now we can use the PHP function array_merge() to take our default array as the first parameter and the user's array as the second parameter. This way we will get an array containing all the keys defined in the $default array and we will not have any options that do not exist. If the user changes one of the old options, its value is retained. With array_merge(), we always keep the latest definitions.

if (!defined('MY_AWESOME_PLUGIN_VERSION'))
    define('MY_AWESOME_PLUGIN_VERSION', '3.4.1');

Finally, we use update_option() to store the results in the database.

function my_awesome_plugin_check_version() {
}

add_action('plugins_loaded', 'my_awesome_plugin_check_version');

We're almost over, but if the function is executed for the first time, we now need to fix an error you might encounter.

This function is called when the plugin is activated, which is what we want. However, in this case the option does not exist yet, so get_option() returns false. The problem is that using false as a parameter of array_merge() will cause an error.

What we want is simple, if the option does not exist, we want $option to be an empty array. To do this, we can use the second parameter of get_option() which indicates the default value to be obtained (in order not to return false).

if (MY_AWESOME_PLUGIN_VERSION !== get_option('my_awesome_plugin_version'))
    my_awesome_plugin_activation();

Conclusion

Once you read it carefully, the process of handling the update of WordPress plugins is not complicated. However, this is important if you use options, as there may be some problems without initialization options.

At present, WordPress does not provide a native way to handle plug-in updates. In fact, given the issues we listed above, if we see that this type of functionality is introduced one day, we should implement it in a way similar to this tutorial.

You can get the code for my sample plugin here. Think of this code as a framework for implementing your own WordPress plugin update process. If you have any feedback, please let me know in the comments below.

WordPress Plugin Update FAQ (FAQ)

What is the importance of regularly updating WordPress plugins?

Regular updates to WordPress plugins are crucial for the following reasons: First, updates often include new features and features that can enhance website performance. Second, updates usually fix bugs and vulnerabilities that may endanger the security of the website. Finally, updates ensure compatibility with the latest version of WordPress, ensuring your website runs smoothly and efficiently.

How to ensure safe updates to my WordPress plugin?

To ensure security updates, be sure to back up your website before starting the update process. This way, if there are any problems during the update process, you can easily restore your website to its previous state. Additionally, it is recommended to test updates on the staging site before applying it to your live site.

What should I do if the plugin update fails?

If the plugin update fails, the first step is to restore your website from the backup. Then, try to determine the cause of the failure. This could be due to a conflict with another plugin or theme, or a compatibility issue with your version of WordPress. Once you have identified the problem, you can fix it yourself, or contact the plugin developer for help.

How to automatically perform the process of updating WordPress plugins?

WordPress has built-in features that allow you to automatically update plugins. You can enable this feature by going to the Plug-in section in the WordPress dashboard, selecting the plug-in you want to update automatically, and clicking Enable Automatic Updates.

If the plugin update causes problems with my website, can I roll back the plugin update?

Yes, if the plugin update causes problems with your website, you can roll back the plugin update. There are several available plugins, such as WP Rollback, that allow you to easily restore to previous versions of the plugin.

How to update advanced WordPress plug-ins?

The advanced WordPress plug-in is updated similarly to the free plug-in. However, you need to have a valid license key to access the update. After entering the license key, you can update the plug-in from the WordPress dashboard.

What is the best way to manage updates to multiple WordPress sites?

If you are managing multiple WordPress sites, you may need to spend a lot of time individually updating plugins for each site. A more efficient way is to use WordPress management tools such as ManageWP or MainWP, which allows you to manage updates for all your websites from a single dashboard.

How to disable automatic updates for specific WordPress plugins?

If you want to disable automatic updates for specific plugins, you can use plugins such as Easy Updates Manager. This plugin allows you to control the automatic updates of each plugin on your website.

How to check for compatibility of plugin updates with my version of WordPress?

Before updating the plugin, you can check its compatibility with your WordPress version by visiting the plugin page on the WordPress plugin directory. Here you will find information about the compatibility of the plug-in with different versions of WordPress.

What should I do if the plugin update breaks my website?

If the plugin update breaks your website, the first step is to restore your website from the backup. Then, deactivate the plugin that caused the problem. If you cannot access your WordPress dashboard, you can deactivate the plug-in via FTP by renaming the plug-in folder in the wp-content/plugins directory. After you disable the plugin, you can troubleshoot or contact the plugin developer for help.

The above is the detailed content of WordPress Plugin Updates the Right Way. For more information, please follow other related articles on the PHP Chinese website!