Skip to content

2 3 Enjoying the Upgrade API

imath edited this page Jun 17, 2018 · 1 revision

The Upgrade UI

Since version 1.1.0, Plugin authors can enjoy the Entrepôt Upgrade API when a new version of their plugin needs to do some specific database edits or migrations. It can be creating a new table, moving a bunch of metadata etc.. So instead of running a quite long task as soon as the plugin is updated, they can register smaller tasks into this new API.

Registering the upgrade tasks

To add your plugin upgrade tasks, you will need to hook to the entrepot_register_upgrade_tasks action and use the entrepot_register_upgrade_tasks() function.

function example_register_upgrade_task() {
	$slug       = 'example';
	$db_version = get_option( 'example-db-version', '1.0.0' );
	$tasks      = array();

	entrepot_register_upgrade_tasks(
		$slug,       // Your plugin's slug
		$db_version, // The version of your plugin saved into the WordPress database. 
		$tasks       // The list of upgrade tasks to run for each stable release needing them.
	)
		
}
add_action( 'entrepot_register_upgrade_tasks', 'example_register_upgrade_task' );

The list of upgrade tasks

This list is an array keyed by version numbers containing a list (another array) of task(s) (another array!). For example it could look like:

$tasks = array(
	'1.1.0' => array(
		array(
			'callback' => 'example_update_db_version_to_1_1',
			'count'    => 'example_return_one',
			'message'  => __( 'Upgrading db version to 1.1', 'example' ),
			'number'   => 1,
		),
	),
	// 1.2.0 has 2 tasks.
	'1.2.0' => array(
		array(
			'callback' => 'example_upgrade_data',
			'count'    => 'example_upgrade_data_count',
			'message'  => __( 'Upgrading a random thing', 'example' ),
			'number'   => 2,
		),
		array(
			'callback' => 'example_update_db_version_to_1_2',
			'count'    => 'example_return_one',
			'message'  => __( 'Upgrading db version to 1.2', 'example' ),
			'number'   => 1,
		),
	),
	'1.3.0' => array(
		array(
			'callback' => 'example_update_db_version_to_1_3',
			'count'    => 'example_return_one',
			'message'  => __( 'Upgrading db version to 1.3', 'example' ),
			'number'   => 1,
		),
	),
);

NB: it's important to order this list according to the version numbers. The Entrepôt Upgrade API will select the tasks a WordPress site needs to do according to the $db_version you specified. In the above example if this version is '1.2.0' only the '1.3.0' tasks will be run. If it's '1.0.0', all tasks (from '1.1.0' to '1.3.0') will be run.

The task parameters

Each task must provide 4 specific parameters:

Parameters Description
callback this is the function that will be used to perform the upgrade task (Make sure it exists!)
count this the function that will count the number of items to upgrade (Make sure it exists!)
message this will be used into the Upgrade UI to inform about the task being processed.
number this is where you define the amount of items to upgrade for each batch.

For example you could create just like the '1.2.0' version upgrade 2 tasks. The first is upgrading 2 items at each batch, and the other is upgrading the db version in a single batch.

BP Reshare 2.0.0 is using this API, as another example, you can view how it's doing it from there.

How the user is informed there are upgrade tasks to perform?

When one or more plugins need to be upgraded Entrepôt will add an Upgrade notice within the Admin Notices Center containing a link to the Entrepôt Upgrade Screen. Once the link clicked, the user will be able to click on the Upgrade button(s) of the listed plugin(s). For the first click, he will be asked for a confirmation containing an advice to backup his database before carrying on.

You can’t perform that action at this time.