wp-includes/cache.php

   1 <?php
   2 /**
   3  * Object Cache API
   4  *
   5  * @link https://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  *
  16  * @global WP_Object_Cache $wp_object_cache
  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 bool False if cache key and group already exist, true on success
  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, (int) $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 true 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  *
  51  * @global WP_Object_Cache $wp_object_cache
  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  *
  69  * @global WP_Object_Cache $wp_object_cache
  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  *
  86  * @global WP_Object_Cache $wp_object_cache
  87  *
  88  * @return bool False on failure, true on success
  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  *
 101  * @global WP_Object_Cache $wp_object_cache
 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  * @param bool &$found Whether key was found in the cache. Disambiguates a return of false, a storable value.
 107  * @return bool|mixed False on failure to retrieve contents or the cache
 108  *                            contents on success
 109  */
 110 function wp_cache_get( $key, $group = '', $force = false, &$found = null ) {
 111         global $wp_object_cache;
 112
 113         return $wp_object_cache->get( $key, $group, $force, $found );
 114 }
 115
 116 /**
 117  * Increment numeric cache item's value
 118  *
 119  * @since 3.3.0
 120  *
 121  * @global WP_Object_Cache $wp_object_cache
 122  *
 123  * @param int|string $key The cache key to increment
 124  * @param int $offset The amount by which to increment the item's value. Default is 1.
 125  * @param string $group The group the key is in.
 126  * @return false|int False on failure, the item's new value on success.
 127  */
 128 function wp_cache_incr( $key, $offset = 1, $group = '' ) {
 129         global $wp_object_cache;
 130
 131         return $wp_object_cache->incr( $key, $offset, $group );
 132 }
 133
 134 /**
 135  * Sets up Object Cache Global and assigns it.
 136  *
 137  * @since 2.0.0
 138  *
 139  * @global WP_Object_Cache $wp_object_cache
 140  */
 141 function wp_cache_init() {
 142         $GLOBALS['wp_object_cache'] = new WP_Object_Cache();
 143 }
 144
 145 /**
 146  * Replaces the contents of the cache with new data.
 147  *
 148  * @since 2.0.0
 149  *
 150  * @global WP_Object_Cache $wp_object_cache
 151  *
 152  * @param int|string $key What to call the contents in the cache
 153  * @param mixed $data The contents to store in the cache
 154  * @param string $group Where to group the cache contents
 155  * @param int $expire When to expire the cache contents
 156  * @return bool False if not exists, true if contents were replaced
 157  */
 158 function wp_cache_replace( $key, $data, $group = '', $expire = 0 ) {
 159         global $wp_object_cache;
 160
 161         return $wp_object_cache->replace( $key, $data, $group, (int) $expire );
 162 }
 163
 164 /**
 165  * Saves the data to the cache.
 166  *
 167  * @since 2.0.0
 168  *
 169  * @global WP_Object_Cache $wp_object_cache
 170  *
 171  * @param int|string $key What to call the contents in the cache
 172  * @param mixed $data The contents to store in the cache
 173  * @param string $group Where to group the cache contents
 174  * @param int $expire When to expire the cache contents
 175  * @return bool False on failure, true on success
 176  */
 177 function wp_cache_set( $key, $data, $group = '', $expire = 0 ) {
 178         global $wp_object_cache;
 179
 180         return $wp_object_cache->set( $key, $data, $group, (int) $expire );
 181 }
 182
 183 /**
 184  * Switch the interal blog id.
 185  *
 186  * This changes the blog id used to create keys in blog specific groups.
 187  *
 188  * @since 3.5.0
 189  *
 190  * @global WP_Object_Cache $wp_object_cache
 191  *
 192  * @param int $blog_id Blog ID
 193  */
 194 function wp_cache_switch_to_blog( $blog_id ) {
 195         global $wp_object_cache;
 196
 197         $wp_object_cache->switch_to_blog( $blog_id );
 198 }
 199
 200 /**
 201  * Adds a group or set of groups to the list of global groups.
 202  *
 203  * @since 2.6.0
 204  *
 205  * @global WP_Object_Cache $wp_object_cache
 206  *
 207  * @param string|array $groups A group or an array of groups to add
 208  */
 209 function wp_cache_add_global_groups( $groups ) {
 210         global $wp_object_cache;
 211
 212         $wp_object_cache->add_global_groups( $groups );
 213 }
 214
 215 /**
 216  * Adds a group or set of groups to the list of non-persistent groups.
 217  *
 218  * @since 2.6.0
 219  *
 220  * @param string|array $groups A group or an array of groups to add
 221  */
 222 function wp_cache_add_non_persistent_groups( $groups ) {
 223         // Default cache doesn't persist so nothing to do here.
 224 }
 225
 226 /**
 227  * Reset internal cache keys and structures. If the cache backend uses global
 228  * blog or site IDs as part of its cache keys, this function instructs the
 229  * backend to reset those keys and perform any cleanup since blog or site IDs
 230  * have changed since cache init.
 231  *
 232  * This function is deprecated. Use wp_cache_switch_to_blog() instead of this
 233  * function when preparing the cache for a blog switch. For clearing the cache
 234  * during unit tests, consider using wp_cache_init(). wp_cache_init() is not
 235  * recommended outside of unit tests as the performance penality for using it is
 236  * high.
 237  *
 238  * @since 2.6.0
 239  * @deprecated 3.5.0
 240  *
 241  * @global WP_Object_Cache $wp_object_cache
 242  */
 243 function wp_cache_reset() {
 244         _deprecated_function( __FUNCTION__, '3.5' );
 245
 246         global $wp_object_cache;
 247
 248         $wp_object_cache->reset();
 249 }
 250
 251 /**
 252  * WordPress Object Cache
 253  *
 254  * The WordPress Object Cache is used to save on trips to the database. The
 255  * Object Cache stores all of the cache data to memory and makes the cache
 256  * contents available by using a key, which is used to name and later retrieve
 257  * the cache contents.
 258  *
 259  * The Object Cache can be replaced by other caching mechanisms by placing files
 260  * in the wp-content folder which is looked at in wp-settings. If that file
 261  * exists, then this file will not be included.
 262  *
 263  * @package WordPress
 264  * @subpackage Cache
 265  * @since 2.0.0
 266  */
 267 class WP_Object_Cache {
 268
 269         /**
 270          * Holds the cached objects
 271          *
 272          * @var array
 273          * @access private
 274          * @since 2.0.0
 275          */
 276         private $cache = array();
 277
 278         /**
 279          * The amount of times the cache data was already stored in the cache.
 280          *
 281          * @since 2.5.0
 282          * @access private
 283          * @var int
 284          */
 285         private $cache_hits = 0;
 286
 287         /**
 288          * Amount of times the cache did not have the request in cache
 289          *
 290          * @var int
 291          * @access public
 292          * @since 2.0.0
 293          */
 294         public $cache_misses = 0;
 295
 296         /**
 297          * List of global groups
 298          *
 299          * @var array
 300          * @access protected
 301          * @since 3.0.0
 302          */
 303         protected $global_groups = array();
 304
 305         /**
 306          * The blog prefix to prepend to keys in non-global groups.
 307          *
 308          * @var int
 309          * @access private
 310          * @since 3.5.0
 311          */
 312         private $blog_prefix;
 313
 314         /**
 315          * Holds the value of `is_multisite()`
 316          *
 317          * @var bool
 318          * @access private
 319          * @since 3.5.0
 320          */
 321         private $multisite;
 322
 323         /**
 324          * Make private properties readable for backwards compatibility.
 325          *
 326          * @since 4.0.0
 327          * @access public
 328          *
 329          * @param string $name Property to get.
 330          * @return mixed Property.
 331          */
 332         public function __get( $name ) {
 333                 return $this->$name;
 334         }
 335
 336         /**
 337          * Make private properties settable for backwards compatibility.
 338          *
 339          * @since 4.0.0
 340          * @access public
 341          *
 342          * @param string $name  Property to set.
 343          * @param mixed  $value Property value.
 344          * @return mixed Newly-set property.
 345          */
 346         public function __set( $name, $value ) {
 347                 return $this->$name = $value;
 348         }
 349
 350         /**
 351          * Make private properties checkable for backwards compatibility.
 352          *
 353          * @since 4.0.0
 354          * @access public
 355          *
 356          * @param string $name Property to check if set.
 357          * @return bool Whether the property is set.
 358          */
 359         public function __isset( $name ) {
 360                 return isset( $this->$name );
 361         }
 362
 363         /**
 364          * Make private properties un-settable for backwards compatibility.
 365          *
 366          * @since 4.0.0
 367          * @access public
 368          *
 369          * @param string $name Property to unset.
 370          */
 371         public function __unset( $name ) {
 372                 unset( $this->$name );
 373         }
 374
 375         /**
 376          * Adds data to the cache if it doesn't already exist.
 377          *
 378          * @uses WP_Object_Cache::_exists Checks to see if the cache already has data.
 379          * @uses WP_Object_Cache::set Sets the data after the checking the cache
 380          *              contents existence.
 381          *
 382          * @since 2.0.0
 383          *
 384          * @param int|string $key What to call the contents in the cache
 385          * @param mixed $data The contents to store in the cache
 386          * @param string $group Where to group the cache contents
 387          * @param int $expire When to expire the cache contents
 388          * @return bool False if cache key and group already exist, true on success
 389          */
 390         public function add( $key, $data, $group = 'default', $expire = 0 ) {
 391                 if ( wp_suspend_cache_addition() )
 392                         return false;
 393
 394                 if ( empty( $group ) )
 395                         $group = 'default';
 396
 397                 $id = $key;
 398                 if ( $this->multisite && ! isset( $this->global_groups[ $group ] ) )
 399                         $id = $this->blog_prefix . $key;
 400
 401                 if ( $this->_exists( $id, $group ) )
 402                         return false;
 403
 404                 return $this->set( $key, $data, $group, (int) $expire );
 405         }
 406
 407         /**
 408          * Sets the list of global groups.
 409          *
 410          * @since 3.0.0
 411          *
 412          * @param array $groups List of groups that are global.
 413          */
 414         public function add_global_groups( $groups ) {
 415                 $groups = (array) $groups;
 416
 417                 $groups = array_fill_keys( $groups, true );
 418                 $this->global_groups = array_merge( $this->global_groups, $groups );
 419         }
 420
 421         /**
 422          * Decrement numeric cache item's value
 423          *
 424          * @since 3.3.0
 425          *
 426          * @param int|string $key The cache key to increment
 427          * @param int $offset The amount by which to decrement the item's value. Default is 1.
 428          * @param string $group The group the key is in.
 429          * @return false|int False on failure, the item's new value on success.
 430          */
 431         public function decr( $key, $offset = 1, $group = 'default' ) {
 432                 if ( empty( $group ) )
 433                         $group = 'default';
 434
 435                 if ( $this->multisite && ! isset( $this->global_groups[ $group ] ) )
 436                         $key = $this->blog_prefix . $key;
 437
 438                 if ( ! $this->_exists( $key, $group ) )
 439                         return false;
 440
 441                 if ( ! is_numeric( $this->cache[ $group ][ $key ] ) )
 442                         $this->cache[ $group ][ $key ] = 0;
 443
 444                 $offset = (int) $offset;
 445
 446                 $this->cache[ $group ][ $key ] -= $offset;
 447
 448                 if ( $this->cache[ $group ][ $key ] < 0 )
 449                         $this->cache[ $group ][ $key ] = 0;
 450
 451                 return $this->cache[ $group ][ $key ];
 452         }
 453
 454         /**
 455          * Remove the contents of the cache key in the group
 456          *
 457          * If the cache key does not exist in the group, then nothing will happen.
 458          *
 459          * @since 2.0.0
 460          *
 461          * @param int|string $key What the contents in the cache are called
 462          * @param string $group Where the cache contents are grouped
 463          * @param bool $deprecated Deprecated.
 464          *
 465          * @return bool False if the contents weren't deleted and true on success
 466          */
 467         public function delete( $key, $group = 'default', $deprecated = false ) {
 468                 if ( empty( $group ) )
 469                         $group = 'default';
 470
 471                 if ( $this->multisite && ! isset( $this->global_groups[ $group ] ) )
 472                         $key = $this->blog_prefix . $key;
 473
 474                 if ( ! $this->_exists( $key, $group ) )
 475                         return false;
 476
 477                 unset( $this->cache[$group][$key] );
 478                 return true;
 479         }
 480
 481         /**
 482          * Clears the object cache of all data
 483          *
 484          * @since 2.0.0
 485          *
 486          * @return true Always returns true
 487          */
 488         public function flush() {
 489                 $this->cache = array();
 490
 491                 return true;
 492         }
 493
 494         /**
 495          * Retrieves the cache contents, if it exists
 496          *
 497          * The contents will be first attempted to be retrieved by searching by the
 498          * key in the cache group. If the cache is hit (success) then the contents
 499          * are returned.
 500          *
 501          * On failure, the number of cache misses will be incremented.
 502          *
 503          * @since 2.0.0
 504          *
 505          * @param int|string $key What the contents in the cache are called
 506          * @param string $group Where the cache contents are grouped
 507          * @param string $force Whether to force a refetch rather than relying on the local cache (default is false)
 508          * @return false|mixed False on failure to retrieve contents or the cache
 509          *                             contents on success
 510          */
 511         public function get( $key, $group = 'default', $force = false, &$found = null ) {
 512                 if ( empty( $group ) )
 513                         $group = 'default';
 514
 515                 if ( $this->multisite && ! isset( $this->global_groups[ $group ] ) )
 516                         $key = $this->blog_prefix . $key;
 517
 518                 if ( $this->_exists( $key, $group ) ) {
 519                         $found = true;
 520                         $this->cache_hits += 1;
 521                         if ( is_object($this->cache[$group][$key]) )
 522                                 return clone $this->cache[$group][$key];
 523                         else
 524                                 return $this->cache[$group][$key];
 525                 }
 526
 527                 $found = false;
 528                 $this->cache_misses += 1;
 529                 return false;
 530         }
 531
 532         /**
 533          * Increment numeric cache item's value
 534          *
 535          * @since 3.3.0
 536          *
 537          * @param int|string $key The cache key to increment
 538          * @param int $offset The amount by which to increment the item's value. Default is 1.
 539          * @param string $group The group the key is in.
 540          * @return false|int False on failure, the item's new value on success.
 541          */
 542         public function incr( $key, $offset = 1, $group = 'default' ) {
 543                 if ( empty( $group ) )
 544                         $group = 'default';
 545
 546                 if ( $this->multisite && ! isset( $this->global_groups[ $group ] ) )
 547                         $key = $this->blog_prefix . $key;
 548
 549                 if ( ! $this->_exists( $key, $group ) )
 550                         return false;
 551
 552                 if ( ! is_numeric( $this->cache[ $group ][ $key ] ) )
 553                         $this->cache[ $group ][ $key ] = 0;
 554
 555                 $offset = (int) $offset;
 556
 557                 $this->cache[ $group ][ $key ] += $offset;
 558
 559                 if ( $this->cache[ $group ][ $key ] < 0 )
 560                         $this->cache[ $group ][ $key ] = 0;
 561
 562                 return $this->cache[ $group ][ $key ];
 563         }
 564
 565         /**
 566          * Replace the contents in the cache, if contents already exist
 567          *
 568          * @since 2.0.0
 569          * @see WP_Object_Cache::set()
 570          *
 571          * @param int|string $key What to call the contents in the cache
 572          * @param mixed $data The contents to store in the cache
 573          * @param string $group Where to group the cache contents
 574          * @param int $expire When to expire the cache contents
 575          * @return bool False if not exists, true if contents were replaced
 576          */
 577         public function replace( $key, $data, $group = 'default', $expire = 0 ) {
 578                 if ( empty( $group ) )
 579                         $group = 'default';
 580
 581                 $id = $key;
 582                 if ( $this->multisite && ! isset( $this->global_groups[ $group ] ) )
 583                         $id = $this->blog_prefix . $key;
 584
 585                 if ( ! $this->_exists( $id, $group ) )
 586                         return false;
 587
 588                 return $this->set( $key, $data, $group, (int) $expire );
 589         }
 590
 591         /**
 592          * Reset keys
 593          *
 594          * @since 3.0.0
 595          * @deprecated 3.5.0
 596          */
 597         public function reset() {
 598                 _deprecated_function( __FUNCTION__, '3.5', 'switch_to_blog()' );
 599
 600                 // Clear out non-global caches since the blog ID has changed.
 601                 foreach ( array_keys( $this->cache ) as $group ) {
 602                         if ( ! isset( $this->global_groups[ $group ] ) )
 603                                 unset( $this->cache[ $group ] );
 604                 }
 605         }
 606
 607         /**
 608          * Sets the data contents into the cache
 609          *
 610          * The cache contents is grouped by the $group parameter followed by the
 611          * $key. This allows for duplicate ids in unique groups. Therefore, naming of
 612          * the group should be used with care and should follow normal function
 613          * naming guidelines outside of core WordPress usage.
 614          *
 615          * The $expire parameter is not used, because the cache will automatically
 616          * expire for each time a page is accessed and PHP finishes. The method is
 617          * more for cache plugins which use files.
 618          *
 619          * @since 2.0.0
 620          *
 621          * @param int|string $key What to call the contents in the cache
 622          * @param mixed $data The contents to store in the cache
 623          * @param string $group Where to group the cache contents
 624          * @param int $expire Not Used
 625          * @return true Always returns true
 626          */
 627         public function set( $key, $data, $group = 'default', $expire = 0 ) {
 628                 if ( empty( $group ) )
 629                         $group = 'default';
 630
 631                 if ( $this->multisite && ! isset( $this->global_groups[ $group ] ) )
 632                         $key = $this->blog_prefix . $key;
 633
 634                 if ( is_object( $data ) )
 635                         $data = clone $data;
 636
 637                 $this->cache[$group][$key] = $data;
 638                 return true;
 639         }
 640
 641         /**
 642          * Echoes the stats of the caching.
 643          *
 644          * Gives the cache hits, and cache misses. Also prints every cached group,
 645          * key and the data.
 646          *
 647          * @since 2.0.0
 648          */
 649         public function stats() {
 650                 echo "<p>";
 651                 echo "<strong>Cache Hits:</strong> {$this->cache_hits}<br />";
 652                 echo "<strong>Cache Misses:</strong> {$this->cache_misses}<br />";
 653                 echo "</p>";
 654                 echo '<ul>';
 655                 foreach ($this->cache as $group => $cache) {
 656                         echo "<li><strong>Group:</strong> $group - ( " . number_format( strlen( serialize( $cache ) ) / 1024, 2 ) . 'k )</li>';
 657                 }
 658                 echo '</ul>';
 659         }
 660
 661         /**
 662          * Switch the interal blog id.
 663          *
 664          * This changes the blog id used to create keys in blog specific groups.
 665          *
 666          * @since 3.5.0
 667          *
 668          * @param int $blog_id Blog ID
 669          */
 670         public function switch_to_blog( $blog_id ) {
 671                 $blog_id = (int) $blog_id;
 672                 $this->blog_prefix = $this->multisite ? $blog_id . ':' : '';
 673         }
 674
 675         /**
 676          * Utility function to determine whether a key exists in the cache.
 677          *
 678          * @since 3.4.0
 679          *
 680          * @access protected
 681          * @param string $key
 682          * @param string $group
 683          * @return bool
 684          */
 685         protected function _exists( $key, $group ) {
 686                 return isset( $this->cache[ $group ] ) && ( isset( $this->cache[ $group ][ $key ] ) || array_key_exists( $key, $this->cache[ $group ] ) );
 687         }
 688
 689         /**
 690          * Sets up object properties; PHP 5 style constructor
 691          *
 692          * @since 2.0.8
 693          *
 694      * @global int $blog_id
 695          */
 696         public function __construct() {
 697                 global $blog_id;
 698
 699                 $this->multisite = is_multisite();
 700                 $this->blog_prefix =  $this->multisite ? $blog_id . ':' : '';
 701
 702
 703                 /**
 704                  * @todo This should be moved to the PHP4 style constructor, PHP5
 705                  * already calls __destruct()
 706                  */
 707                 register_shutdown_function( array( $this, '__destruct' ) );
 708         }
 709
 710         /**
 711          * Will save the object cache before object is completely destroyed.
 712          *
 713          * Called upon object destruction, which should be when PHP ends.
 714          *
 715          * @since  2.0.8
 716          *
 717          * @return true True value. Won't be used by PHP
 718          */
 719         public function __destruct() {
 720                 return true;
 721         }
 722 }