[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       * Adds data to the cache if it doesn't already exist.
 134       *
 135       * @since 2.0.0
 136       *
 137       * @uses WP_Object_Cache::_exists() Checks to see if the cache already has data.
 138       * @uses WP_Object_Cache::set()     Sets the data after the checking the cache
 139       *                                  contents existence.
 140       *
 141       * @param int|string $key    What to call the contents in the cache.
 142       * @param mixed      $data   The contents to store in the cache.
 143       * @param string     $group  Optional. Where to group the cache contents. Default 'default'.
 144       * @param int        $expire Optional. When to expire the cache contents. Default 0 (no expiration).
 145       * @return bool True on success, false if cache key and group already exist.
 146       */
 147  	public function add( $key, $data, $group = 'default', $expire = 0 ) {
 148          if ( wp_suspend_cache_addition() ) {
 149              return false;
 150          }
 151  
 152          if ( empty( $group ) ) {
 153              $group = 'default';
 154          }
 155  
 156          $id = $key;
 157          if ( $this->multisite && ! isset( $this->global_groups[ $group ] ) ) {
 158              $id = $this->blog_prefix . $key;
 159          }
 160  
 161          if ( $this->_exists( $id, $group ) ) {
 162              return false;
 163          }
 164  
 165          return $this->set( $key, $data, $group, (int) $expire );
 166      }
 167  
 168      /**
 169       * Sets the list of global cache groups.
 170       *
 171       * @since 3.0.0
 172       *
 173       * @param array $groups List of groups that are global.
 174       */
 175  	public function add_global_groups( $groups ) {
 176          $groups = (array) $groups;
 177  
 178          $groups              = array_fill_keys( $groups, true );
 179          $this->global_groups = array_merge( $this->global_groups, $groups );
 180      }
 181  
 182      /**
 183       * Decrements numeric cache item's value.
 184       *
 185       * @since 3.3.0
 186       *
 187       * @param int|string $key    The cache key to decrement.
 188       * @param int        $offset Optional. The amount by which to decrement the item's value. Default 1.
 189       * @param string     $group  Optional. The group the key is in. Default 'default'.
 190       * @return int|false The item's new value on success, false on failure.
 191       */
 192  	public function decr( $key, $offset = 1, $group = 'default' ) {
 193          if ( empty( $group ) ) {
 194              $group = 'default';
 195          }
 196  
 197          if ( $this->multisite && ! isset( $this->global_groups[ $group ] ) ) {
 198              $key = $this->blog_prefix . $key;
 199          }
 200  
 201          if ( ! $this->_exists( $key, $group ) ) {
 202              return false;
 203          }
 204  
 205          if ( ! is_numeric( $this->cache[ $group ][ $key ] ) ) {
 206              $this->cache[ $group ][ $key ] = 0;
 207          }
 208  
 209          $offset = (int) $offset;
 210  
 211          $this->cache[ $group ][ $key ] -= $offset;
 212  
 213          if ( $this->cache[ $group ][ $key ] < 0 ) {
 214              $this->cache[ $group ][ $key ] = 0;
 215          }
 216  
 217          return $this->cache[ $group ][ $key ];
 218      }
 219  
 220      /**
 221       * Removes the contents of the cache key in the group.
 222       *
 223       * If the cache key does not exist in the group, then nothing will happen.
 224       *
 225       * @since 2.0.0
 226       *
 227       * @param int|string $key        What the contents in the cache are called.
 228       * @param string     $group      Optional. Where the cache contents are grouped. Default 'default'.
 229       * @param bool       $deprecated Optional. Unused. Default false.
 230       * @return bool False if the contents weren't deleted and true on success.
 231       */
 232  	public function delete( $key, $group = 'default', $deprecated = false ) {
 233          if ( empty( $group ) ) {
 234              $group = 'default';
 235          }
 236  
 237          if ( $this->multisite && ! isset( $this->global_groups[ $group ] ) ) {
 238              $key = $this->blog_prefix . $key;
 239          }
 240  
 241          if ( ! $this->_exists( $key, $group ) ) {
 242              return false;
 243          }
 244  
 245          unset( $this->cache[ $group ][ $key ] );
 246          return true;
 247      }
 248  
 249      /**
 250       * Clears the object cache of all data.
 251       *
 252       * @since 2.0.0
 253       *
 254       * @return true Always returns true.
 255       */
 256  	public function flush() {
 257          $this->cache = array();
 258  
 259          return true;
 260      }
 261  
 262      /**
 263       * Retrieves the cache contents, if it exists.
 264       *
 265       * The contents will be first attempted to be retrieved by searching by the
 266       * key in the cache group. If the cache is hit (success) then the contents
 267       * are returned.
 268       *
 269       * On failure, the number of cache misses will be incremented.
 270       *
 271       * @since 2.0.0
 272       *
 273       * @param int|string $key    What the contents in the cache are called.
 274       * @param string     $group  Optional. Where the cache contents are grouped. Default 'default'.
 275       * @param bool       $force  Optional. Unused. Whether to force a refetch rather than relying on the local
 276       *                           cache. Default false.
 277       * @param bool       $found  Optional. Whether the key was found in the cache (passed by reference).
 278       *                           Disambiguates a return of false, a storable value. Default null.
 279       * @return mixed|false The cache contents on success, false on failure to retrieve contents.
 280       */
 281  	public function get( $key, $group = 'default', $force = false, &$found = null ) {
 282          if ( empty( $group ) ) {
 283              $group = 'default';
 284          }
 285  
 286          if ( $this->multisite && ! isset( $this->global_groups[ $group ] ) ) {
 287              $key = $this->blog_prefix . $key;
 288          }
 289  
 290          if ( $this->_exists( $key, $group ) ) {
 291              $found             = true;
 292              $this->cache_hits += 1;
 293              if ( is_object( $this->cache[ $group ][ $key ] ) ) {
 294                  return clone $this->cache[ $group ][ $key ];
 295              } else {
 296                  return $this->cache[ $group ][ $key ];
 297              }
 298          }
 299  
 300          $found               = false;
 301          $this->cache_misses += 1;
 302          return false;
 303      }
 304  
 305      /**
 306       * Increments numeric cache item's value.
 307       *
 308       * @since 3.3.0
 309       *
 310       * @param int|string $key    The cache key to increment
 311       * @param int        $offset Optional. The amount by which to increment the item's value. Default 1.
 312       * @param string     $group  Optional. The group the key is in. Default 'default'.
 313       * @return int|false The item's new value on success, false on failure.
 314       */
 315  	public function incr( $key, $offset = 1, $group = 'default' ) {
 316          if ( empty( $group ) ) {
 317              $group = 'default';
 318          }
 319  
 320          if ( $this->multisite && ! isset( $this->global_groups[ $group ] ) ) {
 321              $key = $this->blog_prefix . $key;
 322          }
 323  
 324          if ( ! $this->_exists( $key, $group ) ) {
 325              return false;
 326          }
 327  
 328          if ( ! is_numeric( $this->cache[ $group ][ $key ] ) ) {
 329              $this->cache[ $group ][ $key ] = 0;
 330          }
 331  
 332          $offset = (int) $offset;
 333  
 334          $this->cache[ $group ][ $key ] += $offset;
 335  
 336          if ( $this->cache[ $group ][ $key ] < 0 ) {
 337              $this->cache[ $group ][ $key ] = 0;
 338          }
 339  
 340          return $this->cache[ $group ][ $key ];
 341      }
 342  
 343      /**
 344       * Replaces the contents in the cache, if contents already exist.
 345       *
 346       * @since 2.0.0
 347       *
 348       * @see WP_Object_Cache::set()
 349       *
 350       * @param int|string $key    What to call the contents in the cache.
 351       * @param mixed      $data   The contents to store in the cache.
 352       * @param string     $group  Optional. Where to group the cache contents. Default 'default'.
 353       * @param int        $expire Optional. When to expire the cache contents. Default 0 (no expiration).
 354       * @return bool False if not exists, true if contents were replaced.
 355       */
 356  	public function replace( $key, $data, $group = 'default', $expire = 0 ) {
 357          if ( empty( $group ) ) {
 358              $group = 'default';
 359          }
 360  
 361          $id = $key;
 362          if ( $this->multisite && ! isset( $this->global_groups[ $group ] ) ) {
 363              $id = $this->blog_prefix . $key;
 364          }
 365  
 366          if ( ! $this->_exists( $id, $group ) ) {
 367              return false;
 368          }
 369  
 370          return $this->set( $key, $data, $group, (int) $expire );
 371      }
 372  
 373      /**
 374       * Resets cache keys.
 375       *
 376       * @since 3.0.0
 377       *
 378       * @deprecated 3.5.0 Use switch_to_blog()
 379       * @see switch_to_blog()
 380       */
 381  	public function reset() {
 382          _deprecated_function( __FUNCTION__, '3.5.0', 'switch_to_blog()' );
 383  
 384          // Clear out non-global caches since the blog ID has changed.
 385          foreach ( array_keys( $this->cache ) as $group ) {
 386              if ( ! isset( $this->global_groups[ $group ] ) ) {
 387                  unset( $this->cache[ $group ] );
 388              }
 389          }
 390      }
 391  
 392      /**
 393       * Sets the data contents into the cache.
 394       *
 395       * The cache contents are grouped by the $group parameter followed by the
 396       * $key. This allows for duplicate ids in unique groups. Therefore, naming of
 397       * the group should be used with care and should follow normal function
 398       * naming guidelines outside of core WordPress usage.
 399       *
 400       * The $expire parameter is not used, because the cache will automatically
 401       * expire for each time a page is accessed and PHP finishes. The method is
 402       * more for cache plugins which use files.
 403       *
 404       * @since 2.0.0
 405       *
 406       * @param int|string $key    What to call the contents in the cache.
 407       * @param mixed      $data   The contents to store in the cache.
 408       * @param string     $group  Optional. Where to group the cache contents. Default 'default'.
 409       * @param int        $expire Not Used.
 410       * @return true Always returns true.
 411       */
 412  	public function set( $key, $data, $group = 'default', $expire = 0 ) {
 413          if ( empty( $group ) ) {
 414              $group = 'default';
 415          }
 416  
 417          if ( $this->multisite && ! isset( $this->global_groups[ $group ] ) ) {
 418              $key = $this->blog_prefix . $key;
 419          }
 420  
 421          if ( is_object( $data ) ) {
 422              $data = clone $data;
 423          }
 424  
 425          $this->cache[ $group ][ $key ] = $data;
 426          return true;
 427      }
 428  
 429      /**
 430       * Echoes the stats of the caching.
 431       *
 432       * Gives the cache hits, and cache misses. Also prints every cached group,
 433       * key and the data.
 434       *
 435       * @since 2.0.0
 436       */
 437  	public function stats() {
 438          echo '<p>';
 439          echo "<strong>Cache Hits:</strong> {$this->cache_hits}<br />";
 440          echo "<strong>Cache Misses:</strong> {$this->cache_misses}<br />";
 441          echo '</p>';
 442          echo '<ul>';
 443          foreach ( $this->cache as $group => $cache ) {
 444              echo "<li><strong>Group:</strong> $group - ( " . number_format( strlen( serialize( $cache ) ) / KB_IN_BYTES, 2 ) . 'k )</li>';
 445          }
 446          echo '</ul>';
 447      }
 448  
 449      /**
 450       * Switches the internal blog ID.
 451       *
 452       * This changes the blog ID used to create keys in blog specific groups.
 453       *
 454       * @since 3.5.0
 455       *
 456       * @param int $blog_id Blog ID.
 457       */
 458  	public function switch_to_blog( $blog_id ) {
 459          $blog_id           = (int) $blog_id;
 460          $this->blog_prefix = $this->multisite ? $blog_id . ':' : '';
 461      }
 462  
 463      /**
 464       * Serves as a utility function to determine whether a key exists in the cache.
 465       *
 466       * @since 3.4.0
 467       *
 468       * @param int|string $key   Cache key to check for existence.
 469       * @param string     $group Cache group for the key existence check.
 470       * @return bool Whether the key exists in the cache for the given group.
 471       */
 472  	protected function _exists( $key, $group ) {
 473          return isset( $this->cache[ $group ] ) && ( isset( $this->cache[ $group ][ $key ] ) || array_key_exists( $key, $this->cache[ $group ] ) );
 474      }
 475  }