1<?php
  2/**
  3 * Object Cache API
  4 *
  5 * @link https://developer.wordpress.org/reference/classes/wp_object_cache/
  6 *
  7 * @package WordPress
  8 * @subpackage Cache
  9 */
 10
 11/** WP_Object_Cache class */
 12require_once ABSPATH . WPINC . '/class-wp-object-cache.php';
 13
 14/**
 15 * Sets up Object Cache Global and assigns it.
 16 *
 17 * @since 2.0.0
 18 *
 19 * @global WP_Object_Cache $wp_object_cache
 20 */
 21function wp_cache_init() {
 22	$GLOBALS['wp_object_cache'] = new WP_Object_Cache();
 23}
 24
 25/**
 26 * Adds data to the cache, if the cache key doesn't already exist.
 27 *
 28 * @since 2.0.0
 29 *
 30 * @see WP_Object_Cache::add()
 31 * @global WP_Object_Cache $wp_object_cache Object cache global instance.
 32 *
 33 * @param int|string $key    The cache key to use for retrieval later.
 34 * @param mixed      $data   The data to add to the cache.
 35 * @param string     $group  Optional. The group to add the cache to. Enables the same key
 36 *                           to be used across groups. Default empty.
 37 * @param int        $expire Optional. When the cache data should expire, in seconds.
 38 *                           Default 0 (no expiration).
 39 * @return bool True on success, false if cache key and group already exist.
 40 */
 41function wp_cache_add( $key, $data, $group = '', $expire = 0 ) {
 42	global $wp_object_cache;
 43
 44	return $wp_object_cache->add( $key, $data, $group, (int) $expire );
 45}
 46
 47/**
 48 * Adds multiple values to the cache in one call.
 49 *
 50 * @since 6.0.0
 51 *
 52 * @see WP_Object_Cache::add_multiple()
 53 * @global WP_Object_Cache $wp_object_cache Object cache global instance.
 54 *
 55 * @param array  $data   Array of keys and values to be set.
 56 * @param string $group  Optional. Where the cache contents are grouped. Default empty.
 57 * @param int    $expire Optional. When to expire the cache contents, in seconds.
 58 *                       Default 0 (no expiration).
 59 * @return bool[] Array of return values, grouped by key. Each value is either
 60 *                true on success, or false if cache key and group already exist.
 61 */
 62function wp_cache_add_multiple( array $data, $group = '', $expire = 0 ) {
 63	global $wp_object_cache;
 64
 65	return $wp_object_cache->add_multiple( $data, $group, (int) $expire );
 66}
 67
 68/**
 69 * Replaces the contents of the cache with new data.
 70 *
 71 * @since 2.0.0
 72 *
 73 * @see WP_Object_Cache::replace()
 74 * @global WP_Object_Cache $wp_object_cache Object cache global instance.
 75 *
 76 * @param int|string $key    The key for the cache data that should be replaced.
 77 * @param mixed      $data   The new data to store in the cache.
 78 * @param string     $group  Optional. The group for the cache data that should be replaced.
 79 *                           Default empty.
 80 * @param int        $expire Optional. When to expire the cache contents, in seconds.
 81 *                           Default 0 (no expiration).
 82 * @return bool True if contents were replaced, false if original value does not exist.
 83 */
 84function wp_cache_replace( $key, $data, $group = '', $expire = 0 ) {
 85	global $wp_object_cache;
 86
 87	return $wp_object_cache->replace( $key, $data, $group, (int) $expire );
 88}
 89
 90/**
 91 * Saves the data to the cache.
 92 *
 93 * Differs from wp_cache_add() and wp_cache_replace() in that it will always write data.
 94 *
 95 * @since 2.0.0
 96 *
 97 * @see WP_Object_Cache::set()
 98 * @global WP_Object_Cache $wp_object_cache Object cache global instance.
 99 *
100 * @param int|string $key    The cache key to use for retrieval later.
101 * @param mixed      $data   The contents to store in the cache.
102 * @param string     $group  Optional. Where to group the cache contents. Enables the same key
103 *                           to be used across groups. Default empty.
104 * @param int        $expire Optional. When to expire the cache contents, in seconds.
105 *                           Default 0 (no expiration).
106 * @return bool True on success, false on failure.
107 */
108function wp_cache_set( $key, $data, $group = '', $expire = 0 ) {
109	global $wp_object_cache;
110
111	return $wp_object_cache->set( $key, $data, $group, (int) $expire );
112}
113
114/**
115 * Sets multiple values to the cache in one call.
116 *
117 * @since 6.0.0
118 *
119 * @see WP_Object_Cache::set_multiple()
120 * @global WP_Object_Cache $wp_object_cache Object cache global instance.
121 *
122 * @param array  $data   Array of keys and values to be set.
123 * @param string $group  Optional. Where the cache contents are grouped. Default empty.
124 * @param int    $expire Optional. When to expire the cache contents, in seconds.
125 *                       Default 0 (no expiration).
126 * @return bool[] Array of return values, grouped by key. Each value is either
127 *                true on success, or false on failure.
128 */
129function wp_cache_set_multiple( array $data, $group = '', $expire = 0 ) {
130	global $wp_object_cache;
131
132	return $wp_object_cache->set_multiple( $data, $group, (int) $expire );
133}
134
135/**
136 * Retrieves the cache contents from the cache by key and group.
137 *
138 * @since 2.0.0
139 *
140 * @see WP_Object_Cache::get()
141 * @global WP_Object_Cache $wp_object_cache Object cache global instance.
142 *
143 * @param int|string $key   The key under which the cache contents are stored.
144 * @param string     $group Optional. Where the cache contents are grouped. Default empty.
145 * @param bool       $force Optional. Whether to force an update of the local cache
146 *                          from the persistent cache. Default false.
147 * @param bool|null  $found Optional. Whether the key was found in the cache (passed by reference).
148 *                          Disambiguates a return of false, a storable value. Default null.
149 * @return mixed|false The cache contents on success, false on failure to retrieve contents.
150 */
151function wp_cache_get( $key, $group = '', $force = false, &$found = null ) {
152	global $wp_object_cache;
153
154	return $wp_object_cache->get( $key, $group, $force, $found );
155}
156
157/**
158 * Retrieves multiple values from the cache in one call.
159 *
160 * @since 5.5.0
161 *
162 * @see WP_Object_Cache::get_multiple()
163 * @global WP_Object_Cache $wp_object_cache Object cache global instance.
164 *
165 * @param array  $keys  Array of keys under which the cache contents are stored.
166 * @param string $group Optional. Where the cache contents are grouped. Default empty.
167 * @param bool   $force Optional. Whether to force an update of the local cache
168 *                      from the persistent cache. Default false.
169 * @return array Array of return values, grouped by key. Each value is either
170 *               the cache contents on success, or false on failure.
171 */
172function wp_cache_get_multiple( $keys, $group = '', $force = false ) {
173	global $wp_object_cache;
174
175	return $wp_object_cache->get_multiple( $keys, $group, $force );
176}
177
178/**
179 * Removes the cache contents matching key and group.
180 *
181 * @since 2.0.0
182 *
183 * @see WP_Object_Cache::delete()
184 * @global WP_Object_Cache $wp_object_cache Object cache global instance.
185 *
186 * @param int|string $key   What the contents in the cache are called.
187 * @param string     $group Optional. Where the cache contents are grouped. Default empty.
188 * @return bool True on successful removal, false on failure.
189 */
190function wp_cache_delete( $key, $group = '' ) {
191	global $wp_object_cache;
192
193	return $wp_object_cache->delete( $key, $group );
194}
195
196/**
197 * Deletes multiple values from the cache in one call.
198 *
199 * @since 6.0.0
200 *
201 * @see WP_Object_Cache::delete_multiple()
202 * @global WP_Object_Cache $wp_object_cache Object cache global instance.
203 *
204 * @param array  $keys  Array of keys under which the cache to deleted.
205 * @param string $group Optional. Where the cache contents are grouped. Default empty.
206 * @return bool[] Array of return values, grouped by key. Each value is either
207 *                true on success, or false if the contents were not deleted.
208 */
209function wp_cache_delete_multiple( array $keys, $group = '' ) {
210	global $wp_object_cache;
211
212	return $wp_object_cache->delete_multiple( $keys, $group );
213}
214
215/**
216 * Increments numeric cache item's value.
217 *
218 * @since 3.3.0
219 *
220 * @see WP_Object_Cache::incr()
221 * @global WP_Object_Cache $wp_object_cache Object cache global instance.
222 *
223 * @param int|string $key    The key for the cache contents that should be incremented.
224 * @param int        $offset Optional. The amount by which to increment the item's value.
225 *                           Default 1.
226 * @param string     $group  Optional. The group the key is in. Default empty.
227 * @return int|false The item's new value on success, false on failure.
228 */
229function wp_cache_incr( $key, $offset = 1, $group = '' ) {
230	global $wp_object_cache;
231
232	return $wp_object_cache->incr( $key, $offset, $group );
233}
234
235/**
236 * Decrements numeric cache item's value.
237 *
238 * @since 3.3.0
239 *
240 * @see WP_Object_Cache::decr()
241 * @global WP_Object_Cache $wp_object_cache Object cache global instance.
242 *
243 * @param int|string $key    The cache key to decrement.
244 * @param int        $offset Optional. The amount by which to decrement the item's value.
245 *                           Default 1.
246 * @param string     $group  Optional. The group the key is in. Default empty.
247 * @return int|false The item's new value on success, false on failure.
248 */
249function wp_cache_decr( $key, $offset = 1, $group = '' ) {
250	global $wp_object_cache;
251
252	return $wp_object_cache->decr( $key, $offset, $group );
253}
254
255/**
256 * Removes all cache items.
257 *
258 * @since 2.0.0
259 *
260 * @see WP_Object_Cache::flush()
261 * @global WP_Object_Cache $wp_object_cache Object cache global instance.
262 *
263 * @return bool True on success, false on failure.
264 */
265function wp_cache_flush() {
266	global $wp_object_cache;
267
268	return $wp_object_cache->flush();
269}
270
271/**
272 * Removes all cache items from the in-memory runtime cache.
273 *
274 * @since 6.0.0
275 *
276 * @see WP_Object_Cache::flush()
277 *
278 * @return bool True on success, false on failure.
279 */
280function wp_cache_flush_runtime() {
281	return wp_cache_flush();
282}
283
284/**
285 * Removes all cache items in a group, if the object cache implementation supports it.
286 *
287 * Before calling this function, always check for group flushing support using the
288 * `wp_cache_supports( 'flush_group' )` function.
289 *
290 * @since 6.1.0
291 *
292 * @see WP_Object_Cache::flush_group()
293 * @global WP_Object_Cache $wp_object_cache Object cache global instance.
294 *
295 * @param string $group Name of group to remove from cache.
296 * @return bool True if group was flushed, false otherwise.
297 */
298function wp_cache_flush_group( $group ) {
299	global $wp_object_cache;
300
301	return $wp_object_cache->flush_group( $group );
302}
303
304/**
305 * Determines whether the object cache implementation supports a particular feature.
306 *
307 * @since 6.1.0
308 *
309 * @param string $feature Name of the feature to check for. Possible values include:
310 *                        'add_multiple', 'set_multiple', 'get_multiple', 'delete_multiple',
311 *                        'flush_runtime', 'flush_group'.
312 * @return bool True if the feature is supported, false otherwise.
313 */
314function wp_cache_supports( $feature ) {
315	switch ( $feature ) {
316		case 'add_multiple':
317		case 'set_multiple':
318		case 'get_multiple':
319		case 'delete_multiple':
320		case 'flush_runtime':
321		case 'flush_group':
322			return true;
323
324		default:
325			return false;
326	}
327}
328
329/**
330 * Closes the cache.
331 *
332 * This function has ceased to do anything since WordPress 2.5. The
333 * functionality was removed along with the rest of the persistent cache.
334 *
335 * This does not mean that plugins can't implement this function when they need
336 * to make sure that the cache is cleaned up after WordPress no longer needs it.
337 *
338 * @since 2.0.0
339 *
340 * @return true Always returns true.
341 */
342function wp_cache_close() {
343	return true;
344}
345
346/**
347 * Adds a group or set of groups to the list of global groups.
348 *
349 * @since 2.6.0
350 *
351 * @see WP_Object_Cache::add_global_groups()
352 * @global WP_Object_Cache $wp_object_cache Object cache global instance.
353 *
354 * @param string|string[] $groups A group or an array of groups to add.
355 */
356function wp_cache_add_global_groups( $groups ) {
357	global $wp_object_cache;
358
359	$wp_object_cache->add_global_groups( $groups );
360}
361
362/**
363 * Adds a group or set of groups to the list of non-persistent groups.
364 *
365 * @since 2.6.0
366 *
367 * @param string|string[] $groups A group or an array of groups to add.
368 */
369function wp_cache_add_non_persistent_groups( $groups ) {
370	// Default cache doesn't persist so nothing to do here.
371}
372
373/**
374 * Switches the internal blog ID.
375 *
376 * This changes the blog id used to create keys in blog specific groups.
377 *
378 * @since 3.5.0
379 *
380 * @see WP_Object_Cache::switch_to_blog()
381 * @global WP_Object_Cache $wp_object_cache Object cache global instance.
382 *
383 * @param int $blog_id Site ID.
384 */
385function wp_cache_switch_to_blog( $blog_id ) {
386	global $wp_object_cache;
387
388	$wp_object_cache->switch_to_blog( $blog_id );
389}
390
391/**
392 * Resets internal cache keys and structures.
393 *
394 * If the cache back end uses global blog or site IDs as part of its cache keys,
395 * this function instructs the back end to reset those keys and perform any cleanup
396 * since blog or site IDs have changed since cache init.
397 *
398 * This function is deprecated. Use wp_cache_switch_to_blog() instead of this
399 * function when preparing the cache for a blog switch. For clearing the cache
400 * during unit tests, consider using wp_cache_init(). wp_cache_init() is not
401 * recommended outside of unit tests as the performance penalty for using it is high.
402 *
403 * @since 3.0.0
404 * @deprecated 3.5.0 Use wp_cache_switch_to_blog()
405 * @see WP_Object_Cache::reset()
406 *
407 * @global WP_Object_Cache $wp_object_cache Object cache global instance.
408 */
409function wp_cache_reset() {
410	_deprecated_function( __FUNCTION__, '3.5.0', 'wp_cache_switch_to_blog()' );
411
412	global $wp_object_cache;
413
414	$wp_object_cache->reset();
415}
416