WordPress.org

Ready to get started?Download WordPress

Codex

Attention Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Class Reference/WP Object Cache

Role of the WordPress Object Cache

WP_Object_Cache is WordPress' class for caching data which may be computationally expensive to regenerate, such as the result of complex database queries. The object cache is defined in wp-includes/cache.php.

Do not use the class directly in your code when writing plugins, but use the wp_cache functions listed below.

By default, the object cache is non-persistent. This means that data stored in the cache resides in memory only and only for the duration of the request. Cached data will not be stored persistently across page loads unless you install a persistent caching plugin.

Use the Transients API instead of these functions if you need to guarantee that your data will be cached. If persistent caching is configured, then the transients functions will use the wp_cache functions described in this document. However if persistent caching has not been enabled, then the data will instead be cached to the options table.

wp_cache functions

Most of these functions take a:

  • $key: the key to indicate the value.
  • $data: the value you want to store.
  • $group: (optional) this is a way of grouping data within the cache. Allows you to use the same key across different groups.
  • $expire: (optional) this defines how many seconds to keep the cache for. Only applicable to some functions. Defaults to 0 (as long as possible).
wp_cache_add( $key, $data, $group, $expire )

This function adds data to the cache if the cache key doesn't already exist. If it does exist, the data is not added and the function returns false.

wp_cache_set( $key, $data, $group, $expire )

Adds data to the cache. If the cache key already exists, then it will be overwritten; if not then it will be created.

wp_cache_get( $key, $group )
wp_cache_get( $key, $group = '', $force = false, $found = null )

Returns the value of the cached object, or false if the cache key doesn't exist.

To disambiguate a cached false from a non-existing key, you should do absolute testing of $found, which is passed by reference, against false: if $found === false, the key does not exist.

wp_cache_delete( $key, $group )

Clears data from the cache for the given key.

wp_cache_replace( $key, $data, $group, $expire )

Replaces the given cache if it exists, returns false otherwise. This is similar to wp_cache_set() except the cache object is not added if it doesn't already exist.

wp_cache_flush()

Clears all cached data.

wp_cache_add_non_persistent_groups($groups)

Hints to the object cache that the group or list of groups should not be cached in persistent storage. This is useful when adding items to the cache that should only be available for the duration of a script session, and not beyond. $groups can be an array of strings, or a single group name. NB: only some caching plugins implement this function!

Examples

The most common use for the object cache is caching the results of expensive SQL queries so they're not performed multiple times within a page load. In the below example, imagine the $query variable is an expensive SQL query.

$result = wp_cache_get( 'my_result' );
if ( false === $result ) {
	$result = $wpdb->get_results( $query );
	wp_cache_set( 'my_result', $result );
} 
// Do something with $result;

Persistent Caching

Prior to WordPress 2.5, data stored using the wp_cache functions was stored persistently if you added define('WP_CACHE', true) to your wp-config.php file.

This is no longer the case, and adding the define will have no effect unless you install a persistent cache plugin (see list below).

Persistent Cache Plugins

  • W3 Total Cache provides object level caching using disk, opcode or memcache(d) memory stores. W3TC also provides: browser, page and database caching, in addition to Content Delivery Network Support, Mobile Support, Minification and more.
  • Memcached Object Cache provides a persistent backend for the WordPress object cache. A memcached server and the PECL memcached extension are required.
  • APC Object Cache provides a persistent backend for the WordPress object cache using APC, the default opcode and key/value cache of PHP (built-in by default in newer versions of PHP, requires setup on earlier versions).
  • Redis Object Cache uses Redis PECL module to provide a persistent backend for the WordPress object cache. Redis is required.
  • Redis Object Cache uses Predis (PHP client library) to provide a persistent backend for the WordPress object cache. Redis is required.
  • WP File Cache implements object level persistent caching by shifting the load from your database to your disk/file system.
  • File-Based Caching for WordPress re-implements the file-based object caching mechanism found in WordPress 2.1 - 2.3.

Related

The Transients_API provides persistent but temporary data caching by giving it a custom name and a timeframe after which it will be expired and regenerated.

Note: Transients only get deleted when a request is made. So, until someone visits your page and calls up the Transient, it will stay in the DB. In short: It's not a real persistent cache and not equal to stuff running on cron jobs.

Resources

Related

See also index of Class Reference and index of Function Reference.