wp_cache_add() │ WP 2.0.0

Adds data to the cache if there is no cache with the specified key yet.

Differs from wp_cache_set() only in that "add" checks for the existence of the cache. If the cache does not exist yet, control is passed to the method wp_cache_set(); if it exists, the function does nothing and returns false.

Parameter $expire is not used by default because by default, the cache is saved when the page is generated and disappears at the end of the PHP script execution. This parameter is intended for object caching plugins that save the cache to files and the cache is used from the very beginning of the page generation.

Returns

true|false. false if the specified key and cache group already exist; true if the cache was added.

Usage

wp_cache_add( $key, $data, $group, $expire );

$key(int/string) (required): Key for the cache used to access the cache later.
$data(mixed) (required): Data to be added to the cache.
$group(string): Name of the group to which the cache belongs. The group is specified for convenience, so that caches with identical keys can be distinguished by the group they are in.
Default: 'default'
$expire(int): Cache lifetime (in seconds). Not used by default. Intended for object caching plugins.

Examples

#1 Add a cache if you don't have one

To demonstrate how this funciton works.

Let's take the code of function get_the_terms(). The function saves the data into the cache when called and takes the data from the cache when called again and does not make a repeated query to the database.

// I deleted some lines for clarity
function _get_the_terms( $post, $taxonomy ) {
	// try to get the cache
	$terms = get_object_term_cache( $post->ID, $taxonomy );

	if( false === $terms ){
		// no cache, gets terms
		$terms = wp_get_object_terms( $post->ID, $taxonomy );

		if( ! is_wp_error( $terms ) ){
			// add data to the cache
			$term_ids = wp_list_pluck( $terms, 'term_id' );
			wp_cache_add( $post->ID, $term_ids, $taxonomy . '_relationships' );
		}
	}

	return $terms;
}

#2 Using the object cache

This example is useless if you don't use object caching plugins. But if you do, see how much code you don't have to run thanks to the cache:

<?php
function wp_widget_recent_entries( $args ) {

	$cache_key = 'widget_recent_entries';
	$cahe_on = true;

	if( $cahe_on ){
		$output = wp_cache_get( $cache_key, 'widget' );
		if( $output ){
			echo $output;
			return;
		}

		ob_start();
	}

	extract( $args );

	$options = get_option( 'widget_recent_entries' );
	$title = empty( $options['title'] ) ? __( 'Recent Posts' ) : apply_filters( 'widget_title', $options['title'] );

	$number = (int) $options['number'];

	if( ! $number ){
		$number = 10;
	}
	elseif( $number < 1 ){
		$number = 1;
	}
	elseif( $number > 15 ){
		$number = 15;
	}

	$r = new WP_Query( [
		'posts_per_page'   => $number,
		'nopaging'         => 0,
		'post_status'      => 'publish',
		'caller_get_posts' => 1,
	] );

	if( $r->have_posts() ) :

		echo $before_widget;
		if( ! empty( $title ) ){
			echo $before_title . $title . $after_title;
		}
		?>
		<ul>
			<?php while( $r->have_posts() ) : $r->the_post(); ?>
				<li><a href="<?php the_permalink() ?>"><?= esc_html( get_the_title() ?: get_the_ID() ) ?></a></li>
			<?php endwhile; ?>
		</ul>
		<?php
		echo $after_widget;
		wp_reset_query();  // Restore global post data

	endif;

	if( $cahe_on ){
		wp_cache_add( $cache_key, ob_get_flush(), 'widget' );
	}

}
?>

#3 Get statistics on the available cache

You can get these statistics at the end of the PHP script (at the end of the page):

global $wp_object_cache;
$wp_object_cache->stats();

// display information about the cache

Notes

See: WP_Object_Cache::add()
Global. WP_Object_Cache. $wp_object_cache Object cache global instance.

Changelog

Since 2.0.0

Introduced.

`wp_cache_add() wp cache add` code ^{WP 6.9.1}

wp-includes/cache.php

function wp_cache_add( $key, $data, $group = '', $expire = 0 ) {
	global $wp_object_cache;

	return $wp_object_cache->add( $key, $data, $group, (int) $expire );
}