wp_prime_network_option_caches() │ WP 6.6.0

Primes the specified network options into the object cache with one database query.

Only options that are not already cached are loaded.

Options that do not exist in the database are recorded separately so subsequent requests do not create unnecessary queries either.

If Multisite is disabled, the function passes the list to wp_prime_option_caches() and caches regular site options.

Use wp_prime_site_option_caches() when you need to load options for the current network.

Uses: wp_prime_option_caches(), get_current_network_id()
Used By: wp_prime_site_option_caches()

No Hooks.

Returns

null.

  • void - does not return a value.

Usage

wp_prime_network_option_caches( $network_id, $options );
$network_id(int|null) (required)
Network ID.
When null, the current network ID is used.
$options(string[]) (required)
An array of option names to load into the cache.

Examples

#1 Prime options for a specified network

After priming, calls to get_network_option() retrieve the values from the cache.

$network_id = 2;
$options    = [
	'my_plugin_api_url',
	'my_plugin_api_key',
	'my_plugin_enabled',
];

wp_prime_network_option_caches( $network_id, $options );

$api_url = get_network_option( $network_id, 'my_plugin_api_url' );
$api_key = get_network_option( $network_id, 'my_plugin_api_key' );
$enabled = get_network_option( $network_id, 'my_plugin_enabled' );

Notes

Global. wpdb. $wpdb WordPress database abstraction object.

Changelog

Since 6.6.0 Introduced.

wp_prime_network_option_caches() code WP 7.1.2

wp-includes/option.php 
function wp_prime_network_option_caches( $network_id, array $options ) {
	global $wpdb;

	if ( wp_installing() ) {
		return;
	}

	if ( ! is_multisite() ) {
		wp_prime_option_caches( $options );
		return;
	}

	if ( $network_id && ! is_numeric( $network_id ) ) {
		return;
	}

	$network_id = (int) $network_id;

	// Fallback to the current network if a network ID is not specified.
	if ( ! $network_id ) {
		$network_id = get_current_network_id();
	}

	$cache_keys = array();
	foreach ( $options as $option ) {
		$cache_keys[ $option ] = "{$network_id}:{$option}";
	}

	$cache_group    = 'site-options';
	$cached_options = wp_cache_get_multiple( array_values( $cache_keys ), $cache_group );

	$notoptions_key = "$network_id:notoptions";
	$notoptions     = wp_cache_get( $notoptions_key, $cache_group );

	if ( ! is_array( $notoptions ) ) {
		$notoptions = array();
	}

	// Filter options that are not in the cache.
	$options_to_prime = array();
	foreach ( $cache_keys as $option => $cache_key ) {
		if (
			( ! isset( $cached_options[ $cache_key ] ) || false === $cached_options[ $cache_key ] )
			&& ! isset( $notoptions[ $option ] )
		) {
			$options_to_prime[] = $option;
		}
	}

	// Bail early if there are no options to be loaded.
	if ( empty( $options_to_prime ) ) {
		return;
	}

	$query_args   = $options_to_prime;
	$query_args[] = $network_id;
	$results      = $wpdb->get_results(
		$wpdb->prepare(
			sprintf(
				"SELECT meta_key, meta_value FROM $wpdb->sitemeta WHERE meta_key IN (%s) AND site_id = %s",
				implode( ',', array_fill( 0, count( $options_to_prime ), '%s' ) ),
				'%d'
			),
			$query_args
		)
	);

	$data          = array();
	$options_found = array();
	foreach ( $results as $result ) {
		$key                = $result->meta_key;
		$cache_key          = $cache_keys[ $key ];
		$data[ $cache_key ] = maybe_unserialize( $result->meta_value );
		$options_found[]    = $key;
	}
	wp_cache_set_multiple( $data, $cache_group );
	// If all options were found, no need to update `notoptions` cache.
	if ( count( $options_found ) === count( $options_to_prime ) ) {
		return;
	}

	$options_not_found = array_diff( $options_to_prime, $options_found );

	// Add the options that were not found to the cache.
	$update_notoptions = false;
	foreach ( $options_not_found as $option_name ) {
		if ( ! isset( $notoptions[ $option_name ] ) ) {
			$notoptions[ $option_name ] = true;
			$update_notoptions          = true;
		}
	}

	// Only update the cache if it was modified.
	if ( $update_notoptions ) {
		wp_cache_set( $notoptions_key, $notoptions, $cache_group );
	}
}

Options API (settings)

object cache (caching)

Options