wp-includes/cache.php

   1 <?php
   2 /**
   3  * Object Cache API
   4  *
   5  * @link http://codex.wordpress.org/Function_Reference/WP_Cache
   6  *
   7  * @package WordPress
   8  * @subpackage Cache
   9  */
  10
  11 /**
  12  * Adds data to the cache, if the cache key doesn't already exist.
  13  *
  14  * @since 2.0.0
  15  * @uses $wp_object_cache Object Cache Class
  16  * @see WP_Object_Cache::add()
  17  *
  18  * @param int|string $key The cache key to use for retrieval later
  19  * @param mixed $data The data to add to the cache store
  20  * @param string $group The group to add the cache to
  21  * @param int $expire When the cache data should be expired
  22  * @return unknown
  23  */
  24 function wp_cache_add($key, $data, $group = '', $expire = 0) {
  25         global $wp_object_cache;
  26
  27         return $wp_object_cache->add($key, $data, $group, $expire);
  28 }
  29
  30 /**
  31  * Closes the cache.
  32  *
  33  * This function has ceased to do anything since WordPress 2.5. The
  34  * functionality was removed along with the rest of the persistent cache. This
  35  * does not mean that plugins can't implement this function when they need to
  36  * make sure that the cache is cleaned up after WordPress no longer needs it.
  37  *
  38  * @since 2.0.0
  39  *
  40  * @return bool Always returns True
  41  */
  42 function wp_cache_close() {
  43         return true;
  44 }
  45
  46 /**
  47  * Decrement numeric cache item's value
  48  *
  49  * @since 3.3.0
  50  * @uses $wp_object_cache Object Cache Class
  51  * @see WP_Object_Cache::decr()
  52  *
  53  * @param int|string $key The cache key to increment
  54  * @param int $offset The amount by which to decrement the item's value.  Default is 1.
  55  * @param string $group The group the key is in.
  56  * @return false|int False on failure, the item's new value on success.
  57  */
  58 function wp_cache_decr( $key, $offset = 1, $group = '' ) {
  59         global $wp_object_cache;
  60
  61         return $wp_object_cache->decr( $key, $offset, $group );
  62 }
  63
  64 /**
  65  * Removes the cache contents matching key and group.
  66  *
  67  * @since 2.0.0
  68  * @uses $wp_object_cache Object Cache Class
  69  * @see WP_Object_Cache::delete()
  70  *
  71  * @param int|string $key What the contents in the cache are called
  72  * @param string $group Where the cache contents are grouped
  73  * @return bool True on successful removal, false on failure
  74  */
  75 function wp_cache_delete($key, $group = '') {
  76         global $wp_object_cache;
  77
  78         return $wp_object_cache->delete($key, $group);
  79 }
  80
  81 /**
  82  * Removes all cache items.
  83  *
  84  * @since 2.0.0
  85  * @uses $wp_object_cache Object Cache Class
  86  * @see WP_Object_Cache::flush()
  87  *
  88  * @return bool Always returns true
  89  */
  90 function wp_cache_flush() {
  91         global $wp_object_cache;
  92
  93         return $wp_object_cache->flush();
  94 }
  95
  96 /**
  97  * Retrieves the cache contents from the cache by key and group.
  98  *
  99  * @since 2.0.0
 100  * @uses $wp_object_cache Object Cache Class
 101  * @see WP_Object_Cache::get()
 102  *
 103  * @param int|string $key What the contents in the cache are called
 104  * @param string $group Where the cache contents are grouped
 105  * @param bool $force Whether to force an update of the local cache from the persistent cache (default is false)
 106  * @return bool|mixed False on failure to retrieve contents or the cache
 107  *              contents on success
 108  */
 109 function wp_cache_get( $key, $group = '', $force = false ) {
 110         global $wp_object_cache;
 111
 112         return $wp_object_cache->get( $key, $group, $force );
 113 }
 114
 115 /**
 116  * Increment numeric cache item's value
 117  *
 118  * @since 3.3.0
 119  * @uses $wp_object_cache Object Cache Class
 120  * @see WP_Object_Cache::incr()
 121  *
 122  * @param int|string $key The cache key to increment
 123  * @param int $offset The amount by which to increment the item's value.  Default is 1.
 124  * @param string $group The group the key is in.
 125  * @return false|int False on failure, the item's new value on success.
 126  */
 127 function wp_cache_incr( $key, $offset = 1, $group = '' ) {
 128         global $wp_object_cache;
 129
 130         return $wp_object_cache->incr( $key, $offset, $group );
 131 }
 132
 133 /**
 134  * Sets up Object Cache Global and assigns it.
 135  *
 136  * @since 2.0.0
 137  * @global WP_Object_Cache $wp_object_cache WordPress Object Cache
 138  */
 139 function wp_cache_init() {
 140         $GLOBALS['wp_object_cache'] = new WP_Object_Cache();
 141 }
 142
 143 /**
 144  * Replaces the contents of the cache with new data.
 145  *
 146  * @since 2.0.0
 147  * @uses $wp_object_cache Object Cache Class
 148  * @see WP_Object_Cache::replace()
 149  *
 150  * @param int|string $key What to call the contents in the cache
 151  * @param mixed $data The contents to store in the cache
 152  * @param string $group Where to group the cache contents
 153  * @param int $expire When to expire the cache contents
 154  * @return bool False if cache key and group already exist, true on success
 155  */
 156 function wp_cache_replace($key, $data, $group = '', $expire = 0) {
 157         global $wp_object_cache;
 158
 159         return $wp_object_cache->replace($key, $data, $group, $expire);
 160 }
 161
 162 /**
 163  * Saves the data to the cache.
 164  *
 165  * @since 2.0
 166  * @uses $wp_object_cache Object Cache Class
 167  * @see WP_Object_Cache::set()
 168  *
 169  * @param int|string $key What to call the contents in the cache
 170  * @param mixed $data The contents to store in the cache
 171  * @param string $group Where to group the cache contents
 172  * @param int $expire When to expire the cache contents
 173  * @return bool False if cache key and group already exist, true on success
 174  */
 175 function wp_cache_set($key, $data, $group = '', $expire = 0) {
 176         global $wp_object_cache;
 177
 178         return $wp_object_cache->set($key, $data, $group, $expire);
 179 }
 180
 181 /**
 182  * Adds a group or set of groups to the list of global groups.
 183  *
 184  * @since 2.6.0
 185  *
 186  * @param string|array $groups A group or an array of groups to add
 187  */
 188 function wp_cache_add_global_groups( $groups ) {
 189         global $wp_object_cache;
 190
 191         return $wp_object_cache->add_global_groups($groups);
 192 }
 193
 194 /**
 195  * Adds a group or set of groups to the list of non-persistent groups.
 196  *
 197  * @since 2.6.0
 198  *
 199  * @param string|array $groups A group or an array of groups to add
 200  */
 201 function wp_cache_add_non_persistent_groups( $groups ) {
 202         // Default cache doesn't persist so nothing to do here.
 203         return;
 204 }
 205
 206 /**
 207  * Reset internal cache keys and structures.  If the cache backend uses global blog or site IDs as part of its cache keys,
 208  * this function instructs the backend to reset those keys and perform any cleanup since blog or site IDs have changed since cache init.
 209  *
 210  * @since 2.6.0
 211  */
 212 function wp_cache_reset() {
 213         global $wp_object_cache;
 214
 215         return $wp_object_cache->reset();
 216 }
 217
 218 /**
 219  * WordPress Object Cache
 220  *
 221  * The WordPress Object Cache is used to save on trips to the database. The
 222  * Object Cache stores all of the cache data to memory and makes the cache
 223  * contents available by using a key, which is used to name and later retrieve
 224  * the cache contents.
 225  *
 226  * The Object Cache can be replaced by other caching mechanisms by placing files
 227  * in the wp-content folder which is looked at in wp-settings. If that file
 228  * exists, then this file will not be included.
 229  *
 230  * @package WordPress
 231  * @subpackage Cache
 232  * @since 2.0
 233  */
 234 class WP_Object_Cache {
 235
 236         /**
 237          * Holds the cached objects
 238          *
 239          * @var array
 240          * @access private
 241          * @since 2.0.0
 242          */
 243         var $cache = array ();
 244
 245         /**
 246          * The amount of times the cache data was already stored in the cache.
 247          *
 248          * @since 2.5.0
 249          * @access private
 250          * @var int
 251          */
 252         var $cache_hits = 0;
 253
 254         /**
 255          * Amount of times the cache did not have the request in cache
 256          *
 257          * @var int
 258          * @access public
 259          * @since 2.0.0
 260          */
 261         var $cache_misses = 0;
 262
 263         /**
 264          * List of global groups
 265          *
 266          * @var array
 267          * @access protected
 268          * @since 3.0.0
 269          */
 270         var $global_groups = array();
 271
 272         /**
 273          * Adds data to the cache if it doesn't already exist.
 274          *
 275          * @uses WP_Object_Cache::get Checks to see if the cache already has data.
 276          * @uses WP_Object_Cache::set Sets the data after the checking the cache
 277          *              contents existence.
 278          *
 279          * @since 2.0.0
 280          *
 281          * @param int|string $key What to call the contents in the cache
 282          * @param mixed $data The contents to store in the cache
 283          * @param string $group Where to group the cache contents
 284          * @param int $expire When to expire the cache contents
 285          * @return bool False if cache key and group already exist, true on success
 286          */
 287         function add( $key, $data, $group = 'default', $expire = '' ) {
 288                 if ( wp_suspend_cache_addition() )
 289                         return false;
 290
 291                 if ( empty ($group) )
 292                         $group = 'default';
 293
 294                 if (false !== $this->get($key, $group))
 295                         return false;
 296
 297                 return $this->set($key, $data, $group, $expire);
 298         }
 299
 300         /**
 301          * Sets the list of global groups.
 302          *
 303          * @since 3.0.0
 304          *
 305          * @param array $groups List of groups that are global.
 306          */
 307         function add_global_groups( $groups ) {
 308                 $groups = (array) $groups;
 309
 310                 $this->global_groups = array_merge($this->global_groups, $groups);
 311                 $this->global_groups = array_unique($this->global_groups);
 312         }
 313
 314         /**
 315          * Decrement numeric cache item's value
 316          *
 317          * @since 3.3.0
 318          *
 319          * @param int|string $key The cache key to increment
 320          * @param int $offset The amount by which to decrement the item's value.  Default is 1.
 321          * @param string $group The group the key is in.
 322          * @return false|int False on failure, the item's new value on success.
 323          */
 324         function decr( $key, $offset = 1, $group = 'default' ) {
 325                 if ( ! isset( $this->cache[ $group ][ $key ] ) )
 326                         return false;
 327
 328                 if ( ! is_numeric( $this->cache[ $group ][ $key ] ) )
 329                         $this->cache[ $group ][ $key ] = 0;
 330
 331                 $offset = (int) $offset;
 332
 333                 $this->cache[ $group ][ $key ] -= $offset;
 334
 335                 if ( $this->cache[ $group ][ $key ] < 0 )
 336                         $this->cache[ $group ][ $key ] = 0;
 337
 338                 return $this->cache[ $group ][ $key ];
 339         }
 340
 341         /**
 342          * Remove the contents of the cache key in the group
 343          *
 344          * If the cache key does not exist in the group and $force parameter is set
 345          * to false, then nothing will happen. The $force parameter is set to false
 346          * by default.
 347          *
 348          * @since 2.0.0
 349          *
 350          * @param int|string $key What the contents in the cache are called
 351          * @param string $group Where the cache contents are grouped
 352          * @param bool $force Optional. Whether to force the unsetting of the cache
 353          *              key in the group
 354          * @return bool False if the contents weren't deleted and true on success
 355          */
 356         function delete($key, $group = 'default', $force = false) {
 357                 if (empty ($group))
 358                         $group = 'default';
 359
 360                 if (!$force && false === $this->get($key, $group))
 361                         return false;
 362
 363                 unset ($this->cache[$group][$key]);
 364                 return true;
 365         }
 366
 367         /**
 368          * Clears the object cache of all data
 369          *
 370          * @since 2.0.0
 371          *
 372          * @return bool Always returns true
 373          */
 374         function flush() {
 375                 $this->cache = array ();
 376
 377                 return true;
 378         }
 379
 380         /**
 381          * Retrieves the cache contents, if it exists
 382          *
 383          * The contents will be first attempted to be retrieved by searching by the
 384          * key in the cache group. If the cache is hit (success) then the contents
 385          * are returned.
 386          *
 387          * On failure, the number of cache misses will be incremented.
 388          *
 389          * @since 2.0.0
 390          *
 391          * @param int|string $key What the contents in the cache are called
 392          * @param string $group Where the cache contents are grouped
 393          * @param string $force Whether to force a refetch rather than relying on the local cache (default is false)
 394          * @return bool|mixed False on failure to retrieve contents or the cache
 395          *              contents on success
 396          */
 397         function get( $key, $group = 'default', $force = false) {
 398                 if ( empty ($group) )
 399                         $group = 'default';
 400
 401                 if ( isset ($this->cache[$group][$key]) ) {
 402                         $this->cache_hits += 1;
 403                         if ( is_object($this->cache[$group][$key]) )
 404                                 return clone $this->cache[$group][$key];
 405                         else
 406                                 return $this->cache[$group][$key];
 407                 }
 408
 409                 $this->cache_misses += 1;
 410                 return false;
 411         }
 412
 413         /**
 414          * Increment numeric cache item's value
 415          *
 416          * @since 3.3.0
 417          *
 418          * @param int|string $key The cache key to increment
 419          * @param int $offset The amount by which to increment the item's value.  Default is 1.
 420          * @param string $group The group the key is in.
 421          * @return false|int False on failure, the item's new value on success.
 422          */
 423         function incr( $key, $offset = 1, $group = 'default' ) {
 424                 if ( ! isset( $this->cache[ $group ][ $key ] ) )
 425                         return false;
 426
 427                 if ( ! is_numeric( $this->cache[ $group ][ $key ] ) )
 428                         $this->cache[ $group ][ $key ] = 0;
 429
 430                 $offset = (int) $offset;
 431
 432                 $this->cache[ $group ][ $key ] += $offset;
 433
 434                 if ( $this->cache[ $group ][ $key ] < 0 )
 435                         $this->cache[ $group ][ $key ] = 0;
 436
 437                 return $this->cache[ $group ][ $key ];
 438         }
 439
 440         /**
 441          * Replace the contents in the cache, if contents already exist
 442          *
 443          * @since 2.0.0
 444          * @see WP_Object_Cache::set()
 445          *
 446          * @param int|string $key What to call the contents in the cache
 447          * @param mixed $data The contents to store in the cache
 448          * @param string $group Where to group the cache contents
 449          * @param int $expire When to expire the cache contents
 450          * @return bool False if not exists, true if contents were replaced
 451          */
 452         function replace($key, $data, $group = 'default', $expire = '') {
 453                 if (empty ($group))
 454                         $group = 'default';
 455
 456                 if ( false === $this->get($key, $group) )
 457                         return false;
 458
 459                 return $this->set($key, $data, $group, $expire);
 460         }
 461
 462         /**
 463          * Reset keys
 464          *
 465          * @since 3.0.0
 466          */
 467         function reset() {
 468                 // Clear out non-global caches since the blog ID has changed.
 469                 foreach ( array_keys($this->cache) as $group ) {
 470                         if ( !in_array($group, $this->global_groups) )
 471                                 unset($this->cache[$group]);
 472                 }
 473         }
 474
 475         /**
 476          * Sets the data contents into the cache
 477          *
 478          * The cache contents is grouped by the $group parameter followed by the
 479          * $key. This allows for duplicate ids in unique groups. Therefore, naming of
 480          * the group should be used with care and should follow normal function
 481          * naming guidelines outside of core WordPress usage.
 482          *
 483          * The $expire parameter is not used, because the cache will automatically
 484          * expire for each time a page is accessed and PHP finishes. The method is
 485          * more for cache plugins which use files.
 486          *
 487          * @since 2.0.0
 488          *
 489          * @param int|string $key What to call the contents in the cache
 490          * @param mixed $data The contents to store in the cache
 491          * @param string $group Where to group the cache contents
 492          * @param int $expire Not Used
 493          * @return bool Always returns true
 494          */
 495         function set($key, $data, $group = 'default', $expire = '') {
 496                 if ( empty ($group) )
 497                         $group = 'default';
 498
 499                 if ( NULL === $data )
 500                         $data = '';
 501
 502                 if ( is_object($data) )
 503                         $data = clone $data;
 504
 505                 $this->cache[$group][$key] = $data;
 506                 return true;
 507         }
 508
 509         /**
 510          * Echoes the stats of the caching.
 511          *
 512          * Gives the cache hits, and cache misses. Also prints every cached group,
 513          * key and the data.
 514          *
 515          * @since 2.0.0
 516          */
 517         function stats() {
 518                 echo "<p>";
 519                 echo "<strong>Cache Hits:</strong> {$this->cache_hits}<br />";
 520                 echo "<strong>Cache Misses:</strong> {$this->cache_misses}<br />";
 521                 echo "</p>";
 522                 echo '<ul>';
 523                 foreach ($this->cache as $group => $cache) {
 524                         echo "<li><strong>Group:</strong> $group - ( " . number_format( strlen( serialize( $cache ) ) / 1024, 2 ) . 'k )</li>';
 525                 }
 526                 echo '</ul>';
 527         }
 528
 529         /**
 530          * Sets up object properties; PHP 5 style constructor
 531          *
 532          * @since 2.0.8
 533          * @return null|WP_Object_Cache If cache is disabled, returns null.
 534          */
 535         function __construct() {
 536                 /**
 537                  * @todo This should be moved to the PHP4 style constructor, PHP5
 538                  * already calls __destruct()
 539                  */
 540                 register_shutdown_function(array(&$this, "__destruct"));
 541         }
 542
 543         /**
 544          * Will save the object cache before object is completely destroyed.
 545          *
 546          * Called upon object destruction, which should be when PHP ends.
 547          *
 548          * @since  2.0.8
 549          *
 550          * @return bool True value. Won't be used by PHP
 551          */
 552         function __destruct() {
 553                 return true;
 554         }
 555 }
 556 ?>