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.
Most of these functions take a:
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
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!
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;
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).
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.