If you’re a theme or plugin developer and build settings pages into your projects, you’ve probably wondered how to build installation and upgrade methods into them. It’s actually quite simple and requires little code.

The trick I will show you in this tutorial is a bit of an oldie, but it gets the job done. It will give you a simple method for both setting up options and upgrading options when a user installs or updates the theme/plugin.

Defining the database version number

The first thing you must do in your theme/plugin is define the database version number. There are a few things you should keep in mind:

• Define the number early.
• Always use an integer.
• Only change this number when the plugin/theme needs to update its settings.

/* Define your theme/plugin database version. This should only change when new settings are added. */
if ( !defined( 'DEVPRESS_DB_VERSION' ) )
	define( 'DEVPRESS_DB_VERSION', 2 );

You’ll note that I set the database version number to 2 in the previous code. It won’t change with every update of the plugin/theme. This number will stay the same until I need to update settings within the database. Then, it will change to 3, incrementing by 1 each time the settings need to be updated.

Implementing the version check

The next hurdle is creating a function that will check the database version and decide what to do based on the version number (install or update).

The my_version_check() function below is hooked to init. You can certainly change this to another hook such as admin_menu to only run it in the admin. If you’re worried about database queries, don’t be. The option is auto-loaded on every page in WordPress, so this is not a problem.

The following code does a few things:

• Gets the old database version from the database.
• If there's no old version, calls an install function (see "Installation function" below).
• If the defined database version if greater than the user's database version, calls an update function( see "Update function" below).

/* Hook your version check to 'init' to run it on every page. You can use 'admin_menu' to just run it in the admin. */
add_action( 'init', 'my_version_check' );

/* Checks the version number and runs install or update functions if needed. */
function my_version_check() {

	/* Get the old database version. */
	$old_db_version = get_option( 'my_db_version' );

	/* If there is no old database version, run the install. */
	if ( empty( $old_db_version ) )
		my_install();

	/* If the old version is less than the new version, run the update. */
	elseif ( intval( $old_db_version ) < intval( DEVPRESS_DB_VERSION ) )
		my_update();
}

Installation function

The next bit of code you will work with is the installation function. This function will only be called if this is a new install of the plugin/theme. This function adds the my_db_version option to the database and allows you to set up some default settings.

/* Function for installing your theme/plugin settings. */
function my_install() {

	/* Add the database version setting. */
	add_option( 'my_db_version', DEVPRESS_DB_VERSION );

	/* Add your default theme/plugin settings here. */
	// add_option();
}

Update function

Finally, there’s the update function. This function is only called if the defined database version (you did this earlier) is greater than the version saved in the user’s database. It will update the my_db_version and allow you to update the plugin/theme settings with the new settings.

/* Function for updating your theme/plugin settings. */
function my_update() {

	/* Update the database version setting. */
	update_option( 'my_db_version', DEVPRESS_DB_VERSION );

	/* Update the user's new theme/plugin settings here if there are new settings. */
	// get_option(); // Get the previous settings.
	// You'd need to merge the old settings and new settings here.
	// update_option(); // Update the settings.
}

Be careful not to completely overwrite the user’s old settings here. Otherwise, the entire point of the update function is useless.

Conclusion

The code above is meant to be a starting point for your themes and plugins. You’ll certainly want to add custom code to it to fit your individual project needs.

There are a couple of things to remember before implementing this in your projects:

• Be sure to use unique constants and option names. Don't just copy/paste the code from this tutorial into your plugin/theme without changing it to fit your project.
• You'll have to do a little legwork such as actually writing the code to add your theme/plugin settings. I've made ample use of comments in the code, so you should know where to place your custom code.