[Summary view] [Print] [Text view]

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