Recommended usage of the Updates API to support the auto-updates UI for Plugins and Themes in WordPress 5.5

This is an addendum to Controlling Plugin and Theme auto-updates UI in WordPress 5.5.

Edit 8/05/2020: An error in the example of populating no_updates for plugins has been corrected: in site_transient_update_plugins the value of response and no_update are arrays of objects; whereas in site_transient_update_themes, they are arrays of arrays. props @afragen. @pbiron

By default, the enable and disable auto-updates action links for plugins (detailed in the previous developer note) will only appear when the WordPress CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. Updates APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. (available since version 3.7.0) is supported.

All plugins that are hosted in the WordPress Plugin Directory and themes that are hosted in the WordPress Theme Directory already fully support the Updates API and require no changes.

Plugins and themes that are hosted elsewhere (such as premium or “private” plugins) can also support the Updates API with a little bit of code.

Though there is currently no one “official” way for such plugins to support the Updates API, this note offers recommendations for how developers can provide enough support for the auto-updates UIUI User interface to work for their plugins.

Filtering the pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party update transient

The responses received from querying the WordPress.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/ Updates API are stored in the update_plugins site transient. There are several existing filters that developers can use to add information about the availability or lack of available updates for a specific plugin that is not hosted in the WordPress Plugin Directory to that transient. The most common are:

Using pre_set_site_transient_update_plugins, for example, developers can do:

<?php
function myplugin_pre_set_site_transient_update_plugins( $transient ) {
	// Query premium/private repo for updates.
	$update = myplugin_check_for_updates( 'my-plugin' );
	if ( $update ) {
		// Update is available.
		// $update should be an array containing all of the fields in $item below.
		$transient->response['my-plugin/my-plugin.php'] = $update;
	} else {
		// No update is available.
		$item = (object) array(
			'id'            => 'my-plugin/my-plugin.php',
			'slug'          => 'my-plugin',
			'plugin'        => 'my-plugin/my-plugin.php',
			'new_version'   => $myplugin_current_version,
			'url'           => '',
			'package'       => '',
			'icons'         => array(),
			'banners'       => array(),
			'banners_rtl'   => array(),
			'tested'        => '',
			'requires_php'  => '',
			'compatibility' => new stdClass(),
		);
		// Adding the "mock" item to the `no_update` property is required
		// for the enable/disable auto-updates links to correctly appear in UI.
		$transient->no_update['my-plugin/my-plugin.php'] = $item;
	}

	return $transient;
}

add_filter( 'pre_set_site_transient_update_plugins', 'myplugin_pre_set_site_transient_update_plugins' );

Developers that have already been using the Updates API to offer updates for their plugins that are not hosted in the WordPress Plugins Directory have already been populating the response property for their plugin.

The no_update property is a requirement for the auto-update UI to work correctly for externally hosted plugins.

Some are already populating the no_update for their plugin. Any that are not should update their code accordingly for the best user experience.

Filtering the theme update transient

For themes, the responses received from querying the WordPress.org Updates API are stored in the update_themes site transient. The filters used to modify the values of these transients are similar to the ones used for plugins but slightly different:

Using pre_set_site_transient_update_themes, for example, developers of a theme hosted in a different location can do:

<?php
function mytheme_pre_set_site_transient_update_themes( $transient ) {
	// Query premium/private repo for updates.
	$update = mytheme_check_for_updates( 'my-theme' );
	if ( $update ) {
		// Update is available.
		// $update should be an array containing all of the fields in $item below.
		$transient->response['my-theme'] = $update;
	} else {
		// No update is available.
		$item = array(
			'theme'        => 'my-theme',
			'new_version'  => $mytheme_current_version,
			'url'          => '',
			'package'      => '',
			'requires'     => '',
			'requires_php' => '',
		);
		// Adding the "mock" item to the `no_update` property is required
		// for the enable/disable auto-updates links to correctly appear in UI.
		$transient->no_update['my-theme'] = $item;
	}

	return $transient;
}

add_filter( 'pre_set_site_transient_update_themes', 'mytheme_pre_set_site_transient_update_themes' );

The no_update property was only recently added to API responses for theme update queries, and like plugins, the no_update property is a requirement for the auto-update UI to work correctly for externally hosted themes.

Props @desrosj and @audrasjb for review prior to publishing.

#5-5, #auto-update, #auto-updates, #dev-notes, #feature-autoupdates