WordPress 4.5
[autoinstalls/wordpress.git] / wp-includes / cache.php
1 <?php
2 /**
3  * Object Cache API
4  *
5  * @link https://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  *
16  * @see WP_Object_Cache::add()
17  * @global WP_Object_Cache $wp_object_cache Object cache global instance.
18  *
19  * @param int|string $key    The cache key to use for retrieval later.
20  * @param mixed      $data   The data to add to the cache.
21  * @param string     $group  Optional. The group to add the cache to. Enables the same key
22  *                           to be used across groups. Default empty.
23  * @param int        $expire Optional. When the cache data should expire, in seconds.
24  *                           Default 0 (no expiration).
25  * @return bool False if cache key and group already exist, true on success.
26  */
27 function wp_cache_add( $key, $data, $group = '', $expire = 0 ) {
28         global $wp_object_cache;
29
30         return $wp_object_cache->add( $key, $data, $group, (int) $expire );
31 }
32
33 /**
34  * Closes the cache.
35  *
36  * This function has ceased to do anything since WordPress 2.5. The
37  * functionality was removed along with the rest of the persistent cache.
38  *
39  * This does not mean that plugins can't implement this function when they need
40  * to make sure that the cache is cleaned up after WordPress no longer needs it.
41  *
42  * @since 2.0.0
43  *
44  * @return true Always returns true.
45  */
46 function wp_cache_close() {
47         return true;
48 }
49
50 /**
51  * Decrements numeric cache item's value.
52  *
53  * @since 3.3.0
54  *
55  * @see WP_Object_Cache::decr()
56  * @global WP_Object_Cache $wp_object_cache Object cache global instance.
57  *
58  * @param int|string $key    The cache key to decrement.
59  * @param int        $offset Optional. The amount by which to decrement the item's value. Default 1.
60  * @param string     $group  Optional. The group the key is in. Default empty.
61  * @return false|int False on failure, the item's new value on success.
62  */
63 function wp_cache_decr( $key, $offset = 1, $group = '' ) {
64         global $wp_object_cache;
65
66         return $wp_object_cache->decr( $key, $offset, $group );
67 }
68
69 /**
70  * Removes the cache contents matching key and group.
71  *
72  * @since 2.0.0
73  *
74  * @see WP_Object_Cache::delete()
75  * @global WP_Object_Cache $wp_object_cache Object cache global instance.
76  *
77  * @param int|string $key   What the contents in the cache are called.
78  * @param string     $group Optional. Where the cache contents are grouped. Default empty.
79  * @return bool True on successful removal, false on failure.
80  */
81 function wp_cache_delete( $key, $group = '' ) {
82         global $wp_object_cache;
83
84         return $wp_object_cache->delete($key, $group);
85 }
86
87 /**
88  * Removes all cache items.
89  *
90  * @since 2.0.0
91  *
92  * @see WP_Object_Cache::flush()
93  * @global WP_Object_Cache $wp_object_cache Object cache global instance.
94  *
95  * @return bool False on failure, true on success
96  */
97 function wp_cache_flush() {
98         global $wp_object_cache;
99
100         return $wp_object_cache->flush();
101 }
102
103 /**
104  * Retrieves the cache contents from the cache by key and group.
105  *
106  * @since 2.0.0
107  *
108  * @see WP_Object_Cache::get()
109  * @global WP_Object_Cache $wp_object_cache Object cache global instance.
110  *
111  * @param int|string  $key    The key under which the cache contents are stored.
112  * @param string      $group  Optional. Where the cache contents are grouped. Default empty.
113  * @param bool        $force  Optional. Whether to force an update of the local cache from the persistent
114  *                            cache. Default false.
115  * @param bool        $found  Optional. Whether the key was found in the cache. Disambiguates a return of false,
116  *                            a storable value. Passed by reference. Default null.
117  * @return bool|mixed False on failure to retrieve contents or the cache
118  *                            contents on success
119  */
120 function wp_cache_get( $key, $group = '', $force = false, &$found = null ) {
121         global $wp_object_cache;
122
123         return $wp_object_cache->get( $key, $group, $force, $found );
124 }
125
126 /**
127  * Increment numeric cache item's value
128  *
129  * @since 3.3.0
130  *
131  * @see WP_Object_Cache::incr()
132  * @global WP_Object_Cache $wp_object_cache Object cache global instance.
133  *
134  * @param int|string $key    The key for the cache contents that should be incremented.
135  * @param int        $offset Optional. The amount by which to increment the item's value. Default 1.
136  * @param string     $group  Optional. The group the key is in. Default empty.
137  * @return false|int False on failure, the item's new value on success.
138  */
139 function wp_cache_incr( $key, $offset = 1, $group = '' ) {
140         global $wp_object_cache;
141
142         return $wp_object_cache->incr( $key, $offset, $group );
143 }
144
145 /**
146  * Sets up Object Cache Global and assigns it.
147  *
148  * @since 2.0.0
149  *
150  * @global WP_Object_Cache $wp_object_cache
151  */
152 function wp_cache_init() {
153         $GLOBALS['wp_object_cache'] = new WP_Object_Cache();
154 }
155
156 /**
157  * Replaces the contents of the cache with new data.
158  *
159  * @since 2.0.0
160  *
161  * @see WP_Object_Cache::replace()
162  * @global WP_Object_Cache $wp_object_cache Object cache global instance.
163  *
164  * @param int|string $key    The key for the cache data that should be replaced.
165  * @param mixed      $data   The new data to store in the cache.
166  * @param string     $group  Optional. The group for the cache data that should be replaced.
167  *                           Default empty.
168  * @param int        $expire Optional. When to expire the cache contents, in seconds.
169  *                           Default 0 (no expiration).
170  * @return bool False if original value does not exist, true if contents were replaced
171  */
172 function wp_cache_replace( $key, $data, $group = '', $expire = 0 ) {
173         global $wp_object_cache;
174
175         return $wp_object_cache->replace( $key, $data, $group, (int) $expire );
176 }
177
178 /**
179  * Saves the data to the cache.
180  *
181  * Differs from wp_cache_add() and wp_cache_replace() in that it will always write data.
182  *
183  * @since 2.0.0
184  *
185  * @see WP_Object_Cache::set()
186  * @global WP_Object_Cache $wp_object_cache Object cache global instance.
187  *
188  * @param int|string $key    The cache key to use for retrieval later.
189  * @param mixed      $data   The contents to store in the cache.
190  * @param string     $group  Optional. Where to group the cache contents. Enables the same key
191  *                           to be used across groups. Default empty.
192  * @param int        $expire Optional. When to expire the cache contents, in seconds.
193  *                           Default 0 (no expiration).
194  * @return bool False on failure, true on success
195  */
196 function wp_cache_set( $key, $data, $group = '', $expire = 0 ) {
197         global $wp_object_cache;
198
199         return $wp_object_cache->set( $key, $data, $group, (int) $expire );
200 }
201
202 /**
203  * Switches the interal blog ID.
204  *
205  * This changes the blog id used to create keys in blog specific groups.
206  *
207  * @since 3.5.0
208  *
209  * @see WP_Object_Cache::switch_to_blog()
210  * @global WP_Object_Cache $wp_object_cache Object cache global instance.
211  *
212  * @param int $blog_id Site ID.
213  */
214 function wp_cache_switch_to_blog( $blog_id ) {
215         global $wp_object_cache;
216
217         $wp_object_cache->switch_to_blog( $blog_id );
218 }
219
220 /**
221  * Adds a group or set of groups to the list of global groups.
222  *
223  * @since 2.6.0
224  *
225  * @see WP_Object_Cache::add_global_groups()
226  * @global WP_Object_Cache $wp_object_cache Object cache global instance.
227  *
228  * @param string|array $groups A group or an array of groups to add.
229  */
230 function wp_cache_add_global_groups( $groups ) {
231         global $wp_object_cache;
232
233         $wp_object_cache->add_global_groups( $groups );
234 }
235
236 /**
237  * Adds a group or set of groups to the list of non-persistent groups.
238  *
239  * @since 2.6.0
240  *
241  * @param string|array $groups A group or an array of groups to add.
242  */
243 function wp_cache_add_non_persistent_groups( $groups ) {
244         // Default cache doesn't persist so nothing to do here.
245 }
246
247 /**
248  * Reset internal cache keys and structures.
249  *
250  * If the cache back end uses global blog or site IDs as part of its cache keys,
251  * this function instructs the back end to reset those keys and perform any cleanup
252  * since blog or site IDs have changed since cache init.
253  *
254  * This function is deprecated. Use wp_cache_switch_to_blog() instead of this
255  * function when preparing the cache for a blog switch. For clearing the cache
256  * during unit tests, consider using wp_cache_init(). wp_cache_init() is not
257  * recommended outside of unit tests as the performance penality for using it is
258  * high.
259  *
260  * @since 2.6.0
261  * @deprecated 3.5.0 WP_Object_Cache::reset()
262  * @see WP_Object_Cache::reset()
263  *
264  * @global WP_Object_Cache $wp_object_cache Object cache global instance.
265  */
266 function wp_cache_reset() {
267         _deprecated_function( __FUNCTION__, '3.5' );
268
269         global $wp_object_cache;
270
271         $wp_object_cache->reset();
272 }
273
274 /**
275  * Core class that implements an object cache.
276  *
277  * The WordPress Object Cache is used to save on trips to the database. The
278  * Object Cache stores all of the cache data to memory and makes the cache
279  * contents available by using a key, which is used to name and later retrieve
280  * the cache contents.
281  *
282  * The Object Cache can be replaced by other caching mechanisms by placing files
283  * in the wp-content folder which is looked at in wp-settings. If that file
284  * exists, then this file will not be included.
285  *
286  * @package WordPress
287  * @subpackage Cache
288  * @since 2.0.0
289  */
290 class WP_Object_Cache {
291
292         /**
293          * Holds the cached objects.
294          *
295          * @since 2.0.0
296          * @access private
297          * @var array
298          */
299         private $cache = array();
300
301         /**
302          * The amount of times the cache data was already stored in the cache.
303          *
304          * @since 2.5.0
305          * @access private
306          * @var int
307          */
308         private $cache_hits = 0;
309
310         /**
311          * Amount of times the cache did not have the request in cache.
312          *
313          * @since 2.0.0
314          * @access public
315          * @var int
316          */
317         public $cache_misses = 0;
318
319         /**
320          * List of global cache groups.
321          *
322          * @since 3.0.0
323          * @access protected
324          * @var array
325          */
326         protected $global_groups = array();
327
328         /**
329          * The blog prefix to prepend to keys in non-global groups.
330          *
331          * @since 3.5.0
332          * @access private
333          * @var int
334          */
335         private $blog_prefix;
336
337         /**
338          * Holds the value of is_multisite().
339          *
340          * @since 3.5.0
341          * @access private
342          * @var bool
343          */
344         private $multisite;
345
346         /**
347          * Makes private properties readable for backwards compatibility.
348          *
349          * @since 4.0.0
350          * @access public
351          *
352          * @param string $name Property to get.
353          * @return mixed Property.
354          */
355         public function __get( $name ) {
356                 return $this->$name;
357         }
358
359         /**
360          * Makes private properties settable for backwards compatibility.
361          *
362          * @since 4.0.0
363          * @access public
364          *
365          * @param string $name  Property to set.
366          * @param mixed  $value Property value.
367          * @return mixed Newly-set property.
368          */
369         public function __set( $name, $value ) {
370                 return $this->$name = $value;
371         }
372
373         /**
374          * Makes private properties checkable for backwards compatibility.
375          *
376          * @since 4.0.0
377          * @access public
378          *
379          * @param string $name Property to check if set.
380          * @return bool Whether the property is set.
381          */
382         public function __isset( $name ) {
383                 return isset( $this->$name );
384         }
385
386         /**
387          * Makes private properties un-settable for backwards compatibility.
388          *
389          * @since 4.0.0
390          * @access public
391          *
392          * @param string $name Property to unset.
393          */
394         public function __unset( $name ) {
395                 unset( $this->$name );
396         }
397
398         /**
399          * Adds data to the cache if it doesn't already exist.
400          *
401          * @since 2.0.0
402          * @access public
403          *
404          * @uses WP_Object_Cache::_exists() Checks to see if the cache already has data.
405          * @uses WP_Object_Cache::set()     Sets the data after the checking the cache
406          *                                          contents existence.
407          *
408          * @param int|string $key    What to call the contents in the cache.
409          * @param mixed      $data   The contents to store in the cache.
410          * @param string     $group  Optional. Where to group the cache contents. Default 'default'.
411          * @param int        $expire Optional. When to expire the cache contents. Default 0 (no expiration).
412          * @return bool False if cache key and group already exist, true on success
413          */
414         public function add( $key, $data, $group = 'default', $expire = 0 ) {
415                 if ( wp_suspend_cache_addition() )
416                         return false;
417
418                 if ( empty( $group ) )
419                         $group = 'default';
420
421                 $id = $key;
422                 if ( $this->multisite && ! isset( $this->global_groups[ $group ] ) )
423                         $id = $this->blog_prefix . $key;
424
425                 if ( $this->_exists( $id, $group ) )
426                         return false;
427
428                 return $this->set( $key, $data, $group, (int) $expire );
429         }
430
431         /**
432          * Sets the list of global cache groups.
433          *
434          * @since 3.0.0
435          * @access public
436          *
437          * @param array $groups List of groups that are global.
438          */
439         public function add_global_groups( $groups ) {
440                 $groups = (array) $groups;
441
442                 $groups = array_fill_keys( $groups, true );
443                 $this->global_groups = array_merge( $this->global_groups, $groups );
444         }
445
446         /**
447          * Decrements numeric cache item's value.
448          *
449          * @since 3.3.0
450          * @access public
451          *
452          * @param int|string $key    The cache key to decrement.
453          * @param int        $offset Optional. The amount by which to decrement the item's value. Default 1.
454          * @param string     $group  Optional. The group the key is in. Default 'default'.
455          * @return false|int False on failure, the item's new value on success.
456          */
457         public function decr( $key, $offset = 1, $group = 'default' ) {
458                 if ( empty( $group ) )
459                         $group = 'default';
460
461                 if ( $this->multisite && ! isset( $this->global_groups[ $group ] ) )
462                         $key = $this->blog_prefix . $key;
463
464                 if ( ! $this->_exists( $key, $group ) )
465                         return false;
466
467                 if ( ! is_numeric( $this->cache[ $group ][ $key ] ) )
468                         $this->cache[ $group ][ $key ] = 0;
469
470                 $offset = (int) $offset;
471
472                 $this->cache[ $group ][ $key ] -= $offset;
473
474                 if ( $this->cache[ $group ][ $key ] < 0 )
475                         $this->cache[ $group ][ $key ] = 0;
476
477                 return $this->cache[ $group ][ $key ];
478         }
479
480         /**
481          * Removes the contents of the cache key in the group.
482          *
483          * If the cache key does not exist in the group, then nothing will happen.
484          *
485          * @since 2.0.0
486          * @access public
487          *
488          * @param int|string $key        What the contents in the cache are called.
489          * @param string     $group      Optional. Where the cache contents are grouped. Default 'default'.
490          * @param bool       $deprecated Optional. Unused. Default false.
491          * @return bool False if the contents weren't deleted and true on success.
492          */
493         public function delete( $key, $group = 'default', $deprecated = false ) {
494                 if ( empty( $group ) )
495                         $group = 'default';
496
497                 if ( $this->multisite && ! isset( $this->global_groups[ $group ] ) )
498                         $key = $this->blog_prefix . $key;
499
500                 if ( ! $this->_exists( $key, $group ) )
501                         return false;
502
503                 unset( $this->cache[$group][$key] );
504                 return true;
505         }
506
507         /**
508          * Clears the object cache of all data.
509          *
510          * @since 2.0.0
511          * @access public
512          *
513          * @return true Always returns true.
514          */
515         public function flush() {
516                 $this->cache = array();
517
518                 return true;
519         }
520
521         /**
522          * Retrieves the cache contents, if it exists.
523          *
524          * The contents will be first attempted to be retrieved by searching by the
525          * key in the cache group. If the cache is hit (success) then the contents
526          * are returned.
527          *
528          * On failure, the number of cache misses will be incremented.
529          *
530          * @since 2.0.0
531          * @access public
532          *
533          * @param int|string $key    What the contents in the cache are called.
534          * @param string     $group  Optional. Where the cache contents are grouped. Default 'default'.
535          * @param string     $force  Optional. Unused. Whether to force a refetch rather than relying on the local
536          *                           cache. Default false.
537          * @param bool       $found  Optional. Whether the key was found in the cache. Disambiguates a return of
538          *                           false, a storable value. Passed by reference. Default null.
539          * @return false|mixed False on failure to retrieve contents or the cache contents on success.
540          */
541         public function get( $key, $group = 'default', $force = false, &$found = null ) {
542                 if ( empty( $group ) )
543                         $group = 'default';
544
545                 if ( $this->multisite && ! isset( $this->global_groups[ $group ] ) )
546                         $key = $this->blog_prefix . $key;
547
548                 if ( $this->_exists( $key, $group ) ) {
549                         $found = true;
550                         $this->cache_hits += 1;
551                         if ( is_object($this->cache[$group][$key]) )
552                                 return clone $this->cache[$group][$key];
553                         else
554                                 return $this->cache[$group][$key];
555                 }
556
557                 $found = false;
558                 $this->cache_misses += 1;
559                 return false;
560         }
561
562         /**
563          * Increments numeric cache item's value.
564          *
565          * @since 3.3.0
566          * @access public
567          *
568          * @param int|string $key    The cache key to increment
569          * @param int        $offset Optional. The amount by which to increment the item's value. Default 1.
570          * @param string     $group  Optional. The group the key is in. Default 'default'.
571          * @return false|int False on failure, the item's new value on success.
572          */
573         public function incr( $key, $offset = 1, $group = 'default' ) {
574                 if ( empty( $group ) )
575                         $group = 'default';
576
577                 if ( $this->multisite && ! isset( $this->global_groups[ $group ] ) )
578                         $key = $this->blog_prefix . $key;
579
580                 if ( ! $this->_exists( $key, $group ) )
581                         return false;
582
583                 if ( ! is_numeric( $this->cache[ $group ][ $key ] ) )
584                         $this->cache[ $group ][ $key ] = 0;
585
586                 $offset = (int) $offset;
587
588                 $this->cache[ $group ][ $key ] += $offset;
589
590                 if ( $this->cache[ $group ][ $key ] < 0 )
591                         $this->cache[ $group ][ $key ] = 0;
592
593                 return $this->cache[ $group ][ $key ];
594         }
595
596         /**
597          * Replaces the contents in the cache, if contents already exist.
598          *
599          * @since 2.0.0
600          * @access public
601          *
602          * @see WP_Object_Cache::set()
603          *
604          * @param int|string $key    What to call the contents in the cache.
605          * @param mixed      $data   The contents to store in the cache.
606          * @param string     $group  Optional. Where to group the cache contents. Default 'default'.
607          * @param int        $expire Optional. When to expire the cache contents. Default 0 (no expiration).
608          * @return bool False if not exists, true if contents were replaced.
609          */
610         public function replace( $key, $data, $group = 'default', $expire = 0 ) {
611                 if ( empty( $group ) )
612                         $group = 'default';
613
614                 $id = $key;
615                 if ( $this->multisite && ! isset( $this->global_groups[ $group ] ) )
616                         $id = $this->blog_prefix . $key;
617
618                 if ( ! $this->_exists( $id, $group ) )
619                         return false;
620
621                 return $this->set( $key, $data, $group, (int) $expire );
622         }
623
624         /**
625          * Resets cache keys.
626          *
627          * @since 3.0.0
628          * @access public
629          *
630          * @deprecated 3.5.0 Use switch_to_blog()
631          * @see switch_to_blog()
632          */
633         public function reset() {
634                 _deprecated_function( __FUNCTION__, '3.5', 'switch_to_blog()' );
635
636                 // Clear out non-global caches since the blog ID has changed.
637                 foreach ( array_keys( $this->cache ) as $group ) {
638                         if ( ! isset( $this->global_groups[ $group ] ) )
639                                 unset( $this->cache[ $group ] );
640                 }
641         }
642
643         /**
644          * Sets the data contents into the cache.
645          *
646          * The cache contents is grouped by the $group parameter followed by the
647          * $key. This allows for duplicate ids in unique groups. Therefore, naming of
648          * the group should be used with care and should follow normal function
649          * naming guidelines outside of core WordPress usage.
650          *
651          * The $expire parameter is not used, because the cache will automatically
652          * expire for each time a page is accessed and PHP finishes. The method is
653          * more for cache plugins which use files.
654          *
655          * @since 2.0.0
656          * @access public
657          *
658          * @param int|string $key    What to call the contents in the cache.
659          * @param mixed      $data   The contents to store in the cache.
660          * @param string     $group  Optional. Where to group the cache contents. Default 'default'.
661          * @param int        $expire Not Used.
662          * @return true Always returns true.
663          */
664         public function set( $key, $data, $group = 'default', $expire = 0 ) {
665                 if ( empty( $group ) )
666                         $group = 'default';
667
668                 if ( $this->multisite && ! isset( $this->global_groups[ $group ] ) )
669                         $key = $this->blog_prefix . $key;
670
671                 if ( is_object( $data ) )
672                         $data = clone $data;
673
674                 $this->cache[$group][$key] = $data;
675                 return true;
676         }
677
678         /**
679          * Echoes the stats of the caching.
680          *
681          * Gives the cache hits, and cache misses. Also prints every cached group,
682          * key and the data.
683          *
684          * @since 2.0.0
685          * @access public
686          */
687         public function stats() {
688                 echo "<p>";
689                 echo "<strong>Cache Hits:</strong> {$this->cache_hits}<br />";
690                 echo "<strong>Cache Misses:</strong> {$this->cache_misses}<br />";
691                 echo "</p>";
692                 echo '<ul>';
693                 foreach ($this->cache as $group => $cache) {
694                         echo "<li><strong>Group:</strong> $group - ( " . number_format( strlen( serialize( $cache ) ) / KB_IN_BYTES, 2 ) . 'k )</li>';
695                 }
696                 echo '</ul>';
697         }
698
699         /**
700          * Switches the interal blog ID.
701          *
702          * This changes the blog ID used to create keys in blog specific groups.
703          *
704          * @since 3.5.0
705          * @access public
706          *
707          * @param int $blog_id Blog ID.
708          */
709         public function switch_to_blog( $blog_id ) {
710                 $blog_id = (int) $blog_id;
711                 $this->blog_prefix = $this->multisite ? $blog_id . ':' : '';
712         }
713
714         /**
715          * Serves as a utility function to determine whether a key exists in the cache.
716          *
717          * @since 3.4.0
718          * @access protected
719          *
720          * @param int|string $key   Cache key to check for existence.
721          * @param string     $group Cache group for the key existence check.
722          * @return bool Whether the key exists in the cache for the given group.
723          */
724         protected function _exists( $key, $group ) {
725                 return isset( $this->cache[ $group ] ) && ( isset( $this->cache[ $group ][ $key ] ) || array_key_exists( $key, $this->cache[ $group ] ) );
726         }
727
728         /**
729          * Sets up object properties; PHP 5 style constructor.
730          *
731          * @since 2.0.8
732          *
733      * @global int $blog_id Global blog ID.
734          */
735         public function __construct() {
736                 global $blog_id;
737
738                 $this->multisite = is_multisite();
739                 $this->blog_prefix =  $this->multisite ? $blog_id . ':' : '';
740
741
742                 /**
743                  * @todo This should be moved to the PHP4 style constructor, PHP5
744                  * already calls __destruct()
745                  */
746                 register_shutdown_function( array( $this, '__destruct' ) );
747         }
748
749         /**
750          * Saves the object cache before object is completely destroyed.
751          *
752          * Called upon object destruction, which should be when PHP ends.
753          *
754          * @since 2.0.8
755          *
756          * @return true Always returns true.
757          */
758         public function __destruct() {
759                 return true;
760         }
761 }