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 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 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 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  * @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  * @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  * @uses $wp_object_cache Object Cache Class

   121  * @see WP_Object_Cache::incr()

   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  * @global WP_Object_Cache $wp_object_cache WordPress Object Cache

   139  */

   140 function wp_cache_init() {

   141 	$GLOBALS['wp_object_cache'] = new WP_Object_Cache();

   142 }

   143 

   144 /**

   145  * Replaces the contents of the cache with new data.

   146  *

   147  * @since 2.0.0

   148  * @uses $wp_object_cache Object Cache Class

   149  * @see WP_Object_Cache::replace()

   150  *

   151  * @param int|string $key What to call the contents in the cache

   152  * @param mixed $data The contents to store in the cache

   153  * @param string $group Where to group the cache contents

   154  * @param int $expire When to expire the cache contents

   155  * @return bool False if not exists, true if contents were replaced

   156  */

   157 function wp_cache_replace( $key, $data, $group = '', $expire = 0 ) {

   158 	global $wp_object_cache;

   159 

   160 	return $wp_object_cache->replace( $key, $data, $group, (int) $expire );

   161 }

   162 

   163 /**

   164  * Saves the data to the cache.

   165  *

   166  * @since 2.0

   167  * @uses $wp_object_cache Object Cache Class

   168  * @see WP_Object_Cache::set()

   169  *

   170  * @param int|string $key What to call the contents in the cache

   171  * @param mixed $data The contents to store in the cache

   172  * @param string $group Where to group the cache contents

   173  * @param int $expire When to expire the cache contents

   174  * @return bool False on failure, true on success

   175  */

   176 function wp_cache_set( $key, $data, $group = '', $expire = 0 ) {

   177 	global $wp_object_cache;

   178 

   179 	return $wp_object_cache->set( $key, $data, $group, (int) $expire );

   180 }

   181 

   182 /**

   183  * Switch the interal blog id.

   184  *

   185  * This changes the blog id used to create keys in blog specific groups.

   186  *

   187  * @since 3.5.0

   188  *

   189  * @param int $blog_id Blog ID

   190  */

   191 function wp_cache_switch_to_blog( $blog_id ) {

   192 	global $wp_object_cache;

   193 

   194 	return $wp_object_cache->switch_to_blog( $blog_id );

   195 }

   196 

   197 /**

   198  * Adds a group or set of groups to the list of global groups.

   199  *

   200  * @since 2.6.0

   201  *

   202  * @param string|array $groups A group or an array of groups to add

   203  */

   204 function wp_cache_add_global_groups( $groups ) {

   205 	global $wp_object_cache;

   206 

   207 	return $wp_object_cache->add_global_groups( $groups );

   208 }

   209 

   210 /**

   211  * Adds a group or set of groups to the list of non-persistent groups.

   212  *

   213  * @since 2.6.0

   214  *

   215  * @param string|array $groups A group or an array of groups to add

   216  */

   217 function wp_cache_add_non_persistent_groups( $groups ) {

   218 	// Default cache doesn't persist so nothing to do here.

   219 	return;

   220 }

   221 

   222 /**

   223  * Reset internal cache keys and structures. If the cache backend uses global

   224  * blog or site IDs as part of its cache keys, this function instructs the

   225  * backend to reset those keys and perform any cleanup since blog or site IDs

   226  * have changed since cache init.

   227  *

   228  * This function is deprecated. Use wp_cache_switch_to_blog() instead of this

   229  * function when preparing the cache for a blog switch. For clearing the cache

   230  * during unit tests, consider using wp_cache_init(). wp_cache_init() is not

   231  * recommended outside of unit tests as the performance penality for using it is

   232  * high.

   233  *

   234  * @since 2.6.0

   235  * @deprecated 3.5.0

   236  */

   237 function wp_cache_reset() {

   238 	_deprecated_function( __FUNCTION__, '3.5' );

   239 

   240 	global $wp_object_cache;

   241 

   242 	return $wp_object_cache->reset();

   243 }

   244 

   245 /**

   246  * WordPress Object Cache

   247  *

   248  * The WordPress Object Cache is used to save on trips to the database. The

   249  * Object Cache stores all of the cache data to memory and makes the cache

   250  * contents available by using a key, which is used to name and later retrieve

   251  * the cache contents.

   252  *

   253  * The Object Cache can be replaced by other caching mechanisms by placing files

   254  * in the wp-content folder which is looked at in wp-settings. If that file

   255  * exists, then this file will not be included.

   256  *

   257  * @package WordPress

   258  * @subpackage Cache

   259  * @since 2.0

   260  */

   261 class WP_Object_Cache {

   262 

   263 	/**

   264 	 * Holds the cached objects

   265 	 *

   266 	 * @var array

   267 	 * @access private

   268 	 * @since 2.0.0

   269 	 */

   270 	var $cache = array ();

   271 

   272 	/**

   273 	 * The amount of times the cache data was already stored in the cache.

   274 	 *

   275 	 * @since 2.5.0

   276 	 * @access private

   277 	 * @var int

   278 	 */

   279 	var $cache_hits = 0;

   280 

   281 	/**

   282 	 * Amount of times the cache did not have the request in cache

   283 	 *

   284 	 * @var int

   285 	 * @access public

   286 	 * @since 2.0.0

   287 	 */

   288 	var $cache_misses = 0;

   289 

   290 	/**

   291 	 * List of global groups

   292 	 *

   293 	 * @var array

   294 	 * @access protected

   295 	 * @since 3.0.0

   296 	 */

   297 	var $global_groups = array();

   298 

   299 	/**

   300 	 * The blog prefix to prepend to keys in non-global groups.

   301 	 *

   302 	 * @var int

   303 	 * @access private

   304 	 * @since 3.5.0

   305 	 */

   306 	var $blog_prefix;

   307 

   308 	/**

   309 	 * Adds data to the cache if it doesn't already exist.

   310 	 *

   311 	 * @uses WP_Object_Cache::_exists Checks to see if the cache already has data.

   312 	 * @uses WP_Object_Cache::set Sets the data after the checking the cache

   313 	 *		contents existence.

   314 	 *

   315 	 * @since 2.0.0

   316 	 *

   317 	 * @param int|string $key What to call the contents in the cache

   318 	 * @param mixed $data The contents to store in the cache

   319 	 * @param string $group Where to group the cache contents

   320 	 * @param int $expire When to expire the cache contents

   321 	 * @return bool False if cache key and group already exist, true on success

   322 	 */

   323 	function add( $key, $data, $group = 'default', $expire = 0 ) {

   324 		if ( wp_suspend_cache_addition() )

   325 			return false;

   326 

   327 		if ( empty( $group ) )

   328 			$group = 'default';

   329 

   330 		$id = $key;

   331 		if ( $this->multisite && ! isset( $this->global_groups[ $group ] ) )

   332 			$id = $this->blog_prefix . $key;

   333 

   334 		if ( $this->_exists( $id, $group ) )

   335 			return false;

   336 

   337 		return $this->set( $key, $data, $group, (int) $expire );

   338 	}

   339 

   340 	/**

   341 	 * Sets the list of global groups.

   342 	 *

   343 	 * @since 3.0.0

   344 	 *

   345 	 * @param array $groups List of groups that are global.

   346 	 */

   347 	function add_global_groups( $groups ) {

   348 		$groups = (array) $groups;

   349 

   350 		$groups = array_fill_keys( $groups, true );

   351 		$this->global_groups = array_merge( $this->global_groups, $groups );

   352 	}

   353 

   354 	/**

   355 	 * Decrement numeric cache item's value

   356 	 *

   357 	 * @since 3.3.0

   358 	 *

   359 	 * @param int|string $key The cache key to increment

   360 	 * @param int $offset The amount by which to decrement the item's value. Default is 1.

   361 	 * @param string $group The group the key is in.

   362 	 * @return false|int False on failure, the item's new value on success.

   363 	 */

   364 	function decr( $key, $offset = 1, $group = 'default' ) {

   365 		if ( empty( $group ) )

   366 			$group = 'default';

   367 

   368 		if ( $this->multisite && ! isset( $this->global_groups[ $group ] ) )

   369 			$key = $this->blog_prefix . $key;

   370 

   371 		if ( ! $this->_exists( $key, $group ) )

   372 			return false;

   373 

   374 		if ( ! is_numeric( $this->cache[ $group ][ $key ] ) )

   375 			$this->cache[ $group ][ $key ] = 0;

   376 

   377 		$offset = (int) $offset;

   378 

   379 		$this->cache[ $group ][ $key ] -= $offset;

   380 

   381 		if ( $this->cache[ $group ][ $key ] < 0 )

   382 			$this->cache[ $group ][ $key ] = 0;

   383 

   384 		return $this->cache[ $group ][ $key ];

   385 	}

   386 

   387 	/**

   388 	 * Remove the contents of the cache key in the group

   389 	 *

   390 	 * If the cache key does not exist in the group and $force parameter is set

   391 	 * to false, then nothing will happen. The $force parameter is set to false

   392 	 * by default.

   393 	 *

   394 	 * @since 2.0.0

   395 	 *

   396 	 * @param int|string $key What the contents in the cache are called

   397 	 * @param string $group Where the cache contents are grouped

   398 	 * @param bool $force Optional. Whether to force the unsetting of the cache

   399 	 *		key in the group

   400 	 * @return bool False if the contents weren't deleted and true on success

   401 	 */

   402 	function delete($key, $group = 'default', $force = false) {

   403 		if ( empty( $group ) )

   404 			$group = 'default';

   405 

   406 		if ( $this->multisite && ! isset( $this->global_groups[ $group ] ) )

   407 			$key = $this->blog_prefix . $key;

   408 

   409 		if ( ! $force && ! $this->_exists( $key, $group ) )

   410 			return false;

   411 

   412 		unset( $this->cache[$group][$key] );

   413 		return true;

   414 	}

   415 

   416 	/**

   417 	 * Clears the object cache of all data

   418 	 *

   419 	 * @since 2.0.0

   420 	 *

   421 	 * @return bool Always returns true

   422 	 */

   423 	function flush() {

   424 		$this->cache = array ();

   425 

   426 		return true;

   427 	}

   428 

   429 	/**

   430 	 * Retrieves the cache contents, if it exists

   431 	 *

   432 	 * The contents will be first attempted to be retrieved by searching by the

   433 	 * key in the cache group. If the cache is hit (success) then the contents

   434 	 * are returned.

   435 	 *

   436 	 * On failure, the number of cache misses will be incremented.

   437 	 *

   438 	 * @since 2.0.0

   439 	 *

   440 	 * @param int|string $key What the contents in the cache are called

   441 	 * @param string $group Where the cache contents are grouped

   442 	 * @param string $force Whether to force a refetch rather than relying on the local cache (default is false)

   443 	 * @return bool|mixed False on failure to retrieve contents or the cache

   444 	 *		contents on success

   445 	 */

   446 	function get( $key, $group = 'default', $force = false, &$found = null ) {

   447 		if ( empty( $group ) )

   448 			$group = 'default';

   449 

   450 		if ( $this->multisite && ! isset( $this->global_groups[ $group ] ) )

   451 			$key = $this->blog_prefix . $key;

   452 

   453 		if ( $this->_exists( $key, $group ) ) {

   454 			$found = true;

   455 			$this->cache_hits += 1;

   456 			if ( is_object($this->cache[$group][$key]) )

   457 				return clone $this->cache[$group][$key];

   458 			else

   459 				return $this->cache[$group][$key];

   460 		}

   461 

   462 		$found = false;

   463 		$this->cache_misses += 1;

   464 		return false;

   465 	}

   466 

   467 	/**

   468 	 * Increment numeric cache item's value

   469 	 *

   470 	 * @since 3.3.0

   471 	 *

   472 	 * @param int|string $key The cache key to increment

   473 	 * @param int $offset The amount by which to increment the item's value. Default is 1.

   474 	 * @param string $group The group the key is in.

   475 	 * @return false|int False on failure, the item's new value on success.

   476 	 */

   477 	function incr( $key, $offset = 1, $group = 'default' ) {

   478 		if ( empty( $group ) )

   479 			$group = 'default';

   480 

   481 		if ( $this->multisite && ! isset( $this->global_groups[ $group ] ) )

   482 			$key = $this->blog_prefix . $key;

   483 

   484 		if ( ! $this->_exists( $key, $group ) )

   485 			return false;

   486 

   487 		if ( ! is_numeric( $this->cache[ $group ][ $key ] ) )

   488 			$this->cache[ $group ][ $key ] = 0;

   489 

   490 		$offset = (int) $offset;

   491 

   492 		$this->cache[ $group ][ $key ] += $offset;

   493 

   494 		if ( $this->cache[ $group ][ $key ] < 0 )

   495 			$this->cache[ $group ][ $key ] = 0;

   496 

   497 		return $this->cache[ $group ][ $key ];

   498 	}

   499 

   500 	/**

   501 	 * Replace the contents in the cache, if contents already exist

   502 	 *

   503 	 * @since 2.0.0

   504 	 * @see WP_Object_Cache::set()

   505 	 *

   506 	 * @param int|string $key What to call the contents in the cache

   507 	 * @param mixed $data The contents to store in the cache

   508 	 * @param string $group Where to group the cache contents

   509 	 * @param int $expire When to expire the cache contents

   510 	 * @return bool False if not exists, true if contents were replaced

   511 	 */

   512 	function replace( $key, $data, $group = 'default', $expire = 0 ) {

   513 		if ( empty( $group ) )

   514 			$group = 'default';

   515 

   516 		$id = $key;

   517 		if ( $this->multisite && ! isset( $this->global_groups[ $group ] ) )

   518 			$id = $this->blog_prefix . $key;

   519 

   520 		if ( ! $this->_exists( $id, $group ) )

   521 			return false;

   522 

   523 		return $this->set( $key, $data, $group, (int) $expire );

   524 	}

   525 

   526 	/**

   527 	 * Reset keys

   528 	 *

   529 	 * @since 3.0.0

   530 	 * @deprecated 3.5.0

   531 	 */

   532 	function reset() {

   533 		_deprecated_function( __FUNCTION__, '3.5', 'switch_to_blog()' );

   534 

   535 		// Clear out non-global caches since the blog ID has changed.

   536 		foreach ( array_keys( $this->cache ) as $group ) {

   537 			if ( ! isset( $this->global_groups[ $group ] ) )

   538 				unset( $this->cache[ $group ] );

   539 		}

   540 	}

   541 

   542 	/**

   543 	 * Sets the data contents into the cache

   544 	 *

   545 	 * The cache contents is grouped by the $group parameter followed by the

   546 	 * $key. This allows for duplicate ids in unique groups. Therefore, naming of

   547 	 * the group should be used with care and should follow normal function

   548 	 * naming guidelines outside of core WordPress usage.

   549 	 *

   550 	 * The $expire parameter is not used, because the cache will automatically

   551 	 * expire for each time a page is accessed and PHP finishes. The method is

   552 	 * more for cache plugins which use files.

   553 	 *

   554 	 * @since 2.0.0

   555 	 *

   556 	 * @param int|string $key What to call the contents in the cache

   557 	 * @param mixed $data The contents to store in the cache

   558 	 * @param string $group Where to group the cache contents

   559 	 * @param int $expire Not Used

   560 	 * @return bool Always returns true

   561 	 */

   562 	function set( $key, $data, $group = 'default', $expire = 0 ) {

   563 		if ( empty( $group ) )

   564 			$group = 'default';

   565 

   566 		if ( $this->multisite && ! isset( $this->global_groups[ $group ] ) )

   567 			$key = $this->blog_prefix . $key;

   568 

   569 		if ( is_object( $data ) )

   570 			$data = clone $data;

   571 

   572 		$this->cache[$group][$key] = $data;

   573 		return true;

   574 	}

   575 

   576 	/**

   577 	 * Echoes the stats of the caching.

   578 	 *

   579 	 * Gives the cache hits, and cache misses. Also prints every cached group,

   580 	 * key and the data.

   581 	 *

   582 	 * @since 2.0.0

   583 	 */

   584 	function stats() {

   585 		echo "<p>";

   586 		echo "<strong>Cache Hits:</strong> {$this->cache_hits}<br />";

   587 		echo "<strong>Cache Misses:</strong> {$this->cache_misses}<br />";

   588 		echo "</p>";

   589 		echo '<ul>';

   590 		foreach ($this->cache as $group => $cache) {

   591 			echo "<li><strong>Group:</strong> $group - ( " . number_format( strlen( serialize( $cache ) ) / 1024, 2 ) . 'k )</li>';

   592 		}

   593 		echo '</ul>';

   594 	}

   595 

   596 	/**

   597 	 * Switch the interal blog id.

   598 	 *

   599 	 * This changes the blog id used to create keys in blog specific groups.

   600 	 *

   601 	 * @since 3.5.0

   602 	 *

   603 	 * @param int $blog_id Blog ID

   604 	 */

   605 	function switch_to_blog( $blog_id ) {

   606 		$blog_id = (int) $blog_id;

   607 		$this->blog_prefix = $this->multisite ? $blog_id . ':' : '';

   608 	}

   609 

   610 	/**

   611 	 * Utility function to determine whether a key exists in the cache.

   612 	 *

   613 	 * @since 3.4.0

   614 	 *

   615 	 * @access protected

   616 	 */

   617 	protected function _exists( $key, $group ) {

   618 		return isset( $this->cache[ $group ] ) && ( isset( $this->cache[ $group ][ $key ] ) || array_key_exists( $key, $this->cache[ $group ] ) );

   619 	}

   620 

   621 	/**

   622 	 * Sets up object properties; PHP 5 style constructor

   623 	 *

   624 	 * @since 2.0.8

   625 	 * @return null|WP_Object_Cache If cache is disabled, returns null.

   626 	 */

   627 	function __construct() {

   628 		global $blog_id;

   629 

   630 		$this->multisite = is_multisite();

   631 		$this->blog_prefix =  $this->multisite ? $blog_id . ':' : '';

   632 

   633 

   634 		/**

   635 		 * @todo This should be moved to the PHP4 style constructor, PHP5

   636 		 * already calls __destruct()

   637 		 */

   638 		register_shutdown_function( array( $this, '__destruct' ) );

   639 	}

   640 

   641 	/**

   642 	 * Will save the object cache before object is completely destroyed.

   643 	 *

   644 	 * Called upon object destruction, which should be when PHP ends.

   645 	 *

   646 	 * @since  2.0.8

   647 	 *

   648 	 * @return bool True value. Won't be used by PHP

   649 	 */

   650 	function __destruct() {

   651 		return true;

   652 	}

   653 }