Upgrade Actions


Sometimes you may need to perform an action when your plugin is upgraded from version X to version Y. An example is to alter a database table that the plugin uses (such as add a new column).

Background: your plugin looks at two versions:

  1. The version that is in the code of your main plugin file
  2. The version that it secretly saves in the wp_options table
Your plugin tracks what version of your plugin is installed in and XXX_version option (where XXX is your plugin class name prefix). Your code indicates what version it is in its main plugin file (your-plugin-name.php). At the top is a special comment header that is used to give some metadata about your plugin. There is a line there like: “Version: 0.1”.
In plugin class file (XXX_Plugin.php), in the upgrade() function, you would write code to see if the version of the code saved in the DB is less than the version defined in the code. If so, perform your upgrade.
The code looks like this:
public function upgrade() {
    $upgradeOk = true;
    $savedVersion = $this->getVersionSaved();
    if ($this->isVersionLessThan($savedVersion, '2.0')) {
        if ($this->isVersionLessThan($savedVersion, '1.8')) {
            if ($this->isVersionLessThan($savedVersion, '1.5')) {
                // perform version 1.5 upgrade action
            // perform version 1.8 upgrade action
        // perform version 2.0 upgrade action
    // Post-upgrade, set the current version in the options
    $codeVersion = $this->getVersion();
    if ($upgradeOk && $savedVersion != $codeVersion) {

The nesting of the IF’s may seem a little strange at first. For performance we want to avoid checking all the version every time a page is loaded. Every time a page is loaded with the plugin activated, it needs to figure out if it is now activated as a new installed, upgrade, or just a page load. WordPress doesn’t tell the plugin which, so it has to figure it out (happens in the XXX_init.php file). We want to make the overhead of that check minimal. So we put earlier upgrades inside the later upgrade checks. Then we perform upgrades at the end of an IF clause to ensure that upgrades proceed in order.

Imagine in this example, the user had version 1.1 installed then upgraded one time but to version 2.0. We want to ensure that the 1.5 upgrade action happens first, then the 1.8 upgrade, then 2.0. After that, on each page load, on the check for version <2.0 would happen (and fail since it is now 2.0)

At the end of a successful upgrade, you must save the code’s version to the database. This is done by the “saveInstalledVersion” function. In the above example, we added a $upgradeOk variable and check it. This is not necessary, but you might want to check for errors during an upgrade (like can’t do something in the DB because of permissions). If you then do not save the new version to the DB, the upgrade action will be tried again on each page load until it succeeds. You may or may not want this behavior.



  One Response to “Upgrade Actions”

  1. Only trivially less performant, but avoids nesting/indenting if():

    if ($this->isVersionLessThan($savedVersion, ‘2.0’)) {
    if ($this->isVersionLessThan($savedVersion, ‘1.5’)) {
    // perform version 1.5 upgrade action
    if ($this->isVersionLessThan($savedVersion, ‘1.8’)) {
    // perform version 1.8 upgrade action
    if ($this->isVersionLessThan($savedVersion, ‘2.0’)) {
    // perform version 2.0 upgrade action

 Leave a Reply

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>