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.