How to Write a Plugin Update/Upgrade Routine

Learn how to execute code specifically when a plugin is upgraded.
Table of Contents

If you purchase through a link on our site, we may earn a commission.

When creating a new version of your plugin, it is a common need to perform some tasks to complete the upgrade, especially related to the database. Many of you have seen similar functionality when updating WordPress itself. For some version upgrades, WordPress displays a screen and asks your permission to upgrade the database before you can resume using the dashboard.

Sometimes as developers we might change how the plugin stores its data in the database, for example, so we need to write some code that performs the changes as soon as the plugin is upgraded.

What’s the best of handling that?

Well, as on most occasions, we can follow the way WordPress itself does it, as described in the WordPress Codebase Handbook.

The idea is to have a db version stored in a global variable in your plugin. You will also have another db version number stored in the database. Whenever you make any changes to the database schema for your plugin, update the global variable. When the plugin is updated, that will generate a trigger because the global variable won’t match the value stored in the database.

Once we have the trigger we can then execute the code to perform the db upgrade operation, which in the example below is contained in myplugin_install().

So, the code would look like this:

[php]
global $myplugin_db_version;
$myplugin_db_version = "1.0";

function myplugin_install() {
global $wpdb;
global $myplugin_db_version;

$table_name = $wpdb->prefix . "myplugin";

$installed_ver = get_option( "myplugin_db_version" );

if( $installed_ver != $myplugin_db_version ) {

$sql = "CREATE TABLE $table_name (
id mediumint(9) NOT NULL AUTO_INCREMENT,
time datetime DEFAULT ‘0000-00-00 00:00:00’ NOT NULL,
name tinytext NOT NULL,
text text NOT NULL,
url VARCHAR(100) DEFAULT ” NOT NULL,
UNIQUE KEY id (id));
";

require_once(ABSPATH . ‘wp-admin/includes/upgrade.php’);
dbDelta($sql);

update_option( "myplugin_db_version", $myplugin_db_version );

}
}

function myplugin_update_db_check() {
global $myplugin_db_version;
if ( get_site_option( ‘myplugin_db_version’ ) != $myplugin_db_version) {
myplugin_install();
}
}
add_action(‘plugins_loaded’, ‘myplugin_update_db_check’);

[/php]

In the example above we are just creating a new table, but of course you can insert any SQL operation you want there.

Here’s a more generic example:

[php]
function prefix_upgrade_plugin()
{
$v = ‘plugin_db_version’;
$update_option = null;
// Upgrade to version 2
if ( 2 !== get_option( $v ) )
{
if ( 2 < get_option( $v ) )
{
// Callback function must return true on success
$update_option = custom_upgrade_cb_fn_v3();

// Only update option if it was an success
if ( $update_option )
update_option( $v, 2 );
}
}

// Upgrade to version 3, runs just after upgrade to version 2
if ( 3 !== get_option( $v ) )
{
// re-run from beginning if previous update failed
if ( 2 < get_option( $v ) )
return prefix_upgrade_plugin();

if ( 3 < get_option( $v ) )
{
// Callback function must return true on success
$update_option = custom_upgrade_cb_fn_v3();

// Only update option if it was an success
if ( $update_option )
update_option( $v, 3 );
}
}

// Return the result from the update cb fn, so we can test for success/fail/error
if ( $update_option )
return $update_option;

return false;
}
add_action(‘admin_init’, ‘prefix_upgrade_plugin’ );
[/php]

If you came here looking for ways in which you can automatically send plugin update notifications to your users (especially if you own a premium plugin), check out our post about integrating plugin update notifcations within your plugin.

If you enjoyed this post, make sure to subscribe to WPMayor’s RSS feed.

Jean Galea is an investor, entrepreneur, and blogger. He is the founder of WP Mayor, the plugins WP RSS Aggregator and Spotlight, as well as the Mastermind.fm podcast. His personal blog can be found at jeangalea.com.

If you purchase through a link on our site, we may earn a commission.

All suggestions are anonymous.

More from our blog...

Post a Comment

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Stay updated with WP Mayor's newsletter showcase every week

Stay on top of every new WordPress innovation and latest launches. Receive all our fresh product reviews and expert guides directly in your inbox.

Hosting Survey 2024

Are you happy with your hosting provider or are you over-paying for too little? Have your say below!

"*" indicates required fields

What's the main reason you picked this host?*
How happy are you with your host?*

OPTIONAL: If you'd like to receive the results of this survey, please enter your details below.