WordPress 6.4 introduces a number of new functions related to options, with a particular focus on autoloaded options.

While options are autoloaded by default, based on the $autoload parameter of add_option() and update_option(), autoloading too many options is a common cause for slow server response time as well as bugs while using a persistent object cache.

To help plugin developers improve managing their plugins’ options, their performance, and whether to autoload them, two sets of functions are being introduced in 6.4:

• prime_options() and related wrapper functions can be used to fetch multiple options with a single database query.
• wp_set_option_autoload_values() and related wrapper functions can be used to update one or more specific options’ autoload values, independently of their option values.

New functions to retrieve multiple options in a single database query

The prime_options( $options ) function expects an array of option names, and then fetches any options that aren’t already cached with a single database query. The options are then stored in the cache so that subsequent get_option() calls for any of those options do not result in separate database queries.

Note that prime_options() does not return the options as its sole responsibility is to update the relevant caches. In order to actually retrieve multiple options at once, a new wrapper function get_options( $options ) has been introduced. It calls prime_options() for the option names given and then get_option() for every individual option, returning an associative array of option names and their values.

Last but not least, a third function prime_options_by_group() is being introduced, which primes all options of a specific option group (the mandatory first parameter of register_setting()). This can be helpful for plugins to fetch all options of a specific option group the plugin uses.

All of the above functions have been introduced not only as a performant way to retrieve multiple options from the database, but also as an alternative to autoloading options that are only needed in a few specific areas. For example, a plugin that currently autoloads a few options which are only used on the plugin’s own WP Admin screen would be encouraged to use the new prime_options() or prime_options_by_group() instead of autoloading the options.

Example

In this example, we assume a plugin has a WP Admin screen that relies on four options: “myplugin_foo”, “myplugin_bar”, “myplugin_foobar”, and “myplugin_barfoo”. All of these options are only used on that admin screen and therefore should not be autoloaded. In other words, any add_option() and update_option() calls for those options should provide “no” for the $autoload parameter.

function myplugin_prime_admin_screen_options() {
	/*
	 * By priming the options here, no further database queries will be used
	 * when later calling `get_option()`.
	 */
	prime_options(
		array( 'myplugin_foo', 'myplugin_bar', 'myplugin_foobar', 'myplugin_barfoo' )
	);
}

function myplugin_add_admin_screen() {
	$hook_suffix = add_menu_page( /* Menu page arguments. */ );
	add_action( "load-{$hook_suffix}", 'myplugin_prime_admin_screen_options' );
}
add_action( 'admin_menu', 'myplugin_add_admin_screen' );

This code would ensure that the options are retrieved in a single database query. Any subsequent get_option() calls for these options would then not result in another database query and thus be extremely fast. As such, the WP Admin screen is just as performant as it would have been with autoloading those options, yet without unnecessarily slowing down performance of the entire site.

To further enhance that example, the plugin could rely on a single option group for which it registers those options. Here is the example code for that:

function myplugin_register_settings() {
	register_setting(
		'myplugin_admin_screen',
		'myplugin_foo',
		array( /* Registration arguments. */ )
	);
	register_setting(
		'myplugin_admin_screen',
		'myplugin_bar',
		array( /* Registration arguments. */ )
	);
	register_setting(
		'myplugin_admin_screen',
		'myplugin_foobar',
		array( /* Registration arguments. */ )
	);
	register_setting(
		'myplugin_admin_screen',
		'myplugin_barfoo',
		array( /* Registration arguments. */ )
	);
}
add_action( 'init', 'myplugin_register_settings' );

function myplugin_prime_admin_screen_options() {
	/*
	 * By priming the options here, no further database queries will be used
	 * when later calling `get_option()`.
	 */
	prime_options_by_group( 'myplugin_admin_screen' );
}

// `myplugin_add_admin_screen()` would remain as in the previous code example.

With that adjustment, the option registration would be the central place to manage the options, and the myplugin_prime_admin_screen_options() function would remain simple without maintaining a list of the exact options.

Please refer to Trac ticket #58962 for additional details on these changes.

New functions to set option autoload values

The wp_set_option_autoload_values( array $options ) function expects an associative array of option names and their autoload values to set, and then updates those options’ autoload values in a single database query.

Additionally, two wrapper functions for the above are also being introduced for ease of use:

• wp_set_options_autoload( $options, $autoload ) can be used to set multiple options to the same autoload value.
• wp_set_option_autoload( $option, $autoload ) can be used to set the autoload value for a single option.

These functions can be useful in a plugin deactivation hook: After deactivation, the plugin’s options won’t be used anymore, yet they should not be deleted from the database until the user decides to uninstall the plugin.

Example

In this example, we assume a plugin has two options “myplugin_foo” and “myplugin_bar”, both of which are used in various frontend page loads and therefore autoloaded by default. To properly clean up after itself, such a plugin could implement usage of the new functions as follows:

function myplugin_activate() {
	wp_set_options_autoload(
		array( 'myplugin_foo', 'myplugin_bar' ),
		'yes'
	);
}
register_activation_hook( __FILE__, 'myplugin_activate' );

function myplugin_deactivate() {
	wp_set_options_autoload(
		array( 'myplugin_foo', 'myplugin_bar' ),
		'no'
	);
}
register_deactivation_hook( __FILE__, 'myplugin_deactivate' );

This code would ensure that the options are no longer autoloaded when the plugin has been deactivated. If the plugin gets (re-)activated, the options will be set to autoload again if they are already in the database.

Please refer to Trac ticket #58964 for additional details on these changes.

Related autoload bug fix for update_option()

While not directly tied to the above functions, it is worth noting that a bug relevant to autoloading has been addressed in 6.4: When using the $autoload parameter of update_option() alongside an option value update, the function would update the incorrect cache, not respecting the new autoload value. This could have severe implications such as returning a stale option value when the option in fact had already been deleted.

This bug has been fixed in 6.4, so that the $autoload parameter of update_option() can now be reliably used to change the option’s autoload value. It should be noted though that depending on the use-case the above functions to set option autoload values may be more suitable.

Please refer to Trac ticket #51352 for additional details on this bug fix.

Props to @westonruter and @webcommsat for review and proofreading.

#6-4, #dev-notes, #dev-notes-6-4, #performance