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