Wordpress 3.3.1
[autoinstalls/wordpress.git] / wp-includes / cache.php
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 unknown
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, $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 Always returns true
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  * @return bool|mixed False on failure to retrieve contents or the cache
107  *              contents on success
108  */
109 function wp_cache_get( $key, $group = '', $force = false ) {
110         global $wp_object_cache;
111
112         return $wp_object_cache->get( $key, $group, $force );
113 }
114
115 /**
116  * Increment numeric cache item's value
117  *
118  * @since 3.3.0
119  * @uses $wp_object_cache Object Cache Class
120  * @see WP_Object_Cache::incr()
121  *
122  * @param int|string $key The cache key to increment
123  * @param int $offset The amount by which to increment the item's value.  Default is 1.
124  * @param string $group The group the key is in.
125  * @return false|int False on failure, the item's new value on success.
126  */
127 function wp_cache_incr( $key, $offset = 1, $group = '' ) {
128         global $wp_object_cache;
129
130         return $wp_object_cache->incr( $key, $offset, $group );
131 }
132
133 /**
134  * Sets up Object Cache Global and assigns it.
135  *
136  * @since 2.0.0
137  * @global WP_Object_Cache $wp_object_cache WordPress Object Cache
138  */
139 function wp_cache_init() {
140         $GLOBALS['wp_object_cache'] = new WP_Object_Cache();
141 }
142
143 /**
144  * Replaces the contents of the cache with new data.
145  *
146  * @since 2.0.0
147  * @uses $wp_object_cache Object Cache Class
148  * @see WP_Object_Cache::replace()
149  *
150  * @param int|string $key What to call the contents in the cache
151  * @param mixed $data The contents to store in the cache
152  * @param string $group Where to group the cache contents
153  * @param int $expire When to expire the cache contents
154  * @return bool False if cache key and group already exist, true on success
155  */
156 function wp_cache_replace($key, $data, $group = '', $expire = 0) {
157         global $wp_object_cache;
158
159         return $wp_object_cache->replace($key, $data, $group, $expire);
160 }
161
162 /**
163  * Saves the data to the cache.
164  *
165  * @since 2.0
166  * @uses $wp_object_cache Object Cache Class
167  * @see WP_Object_Cache::set()
168  *
169  * @param int|string $key What to call the contents in the cache
170  * @param mixed $data The contents to store in the cache
171  * @param string $group Where to group the cache contents
172  * @param int $expire When to expire the cache contents
173  * @return bool False if cache key and group already exist, true on success
174  */
175 function wp_cache_set($key, $data, $group = '', $expire = 0) {
176         global $wp_object_cache;
177
178         return $wp_object_cache->set($key, $data, $group, $expire);
179 }
180
181 /**
182  * Adds a group or set of groups to the list of global groups.
183  *
184  * @since 2.6.0
185  *
186  * @param string|array $groups A group or an array of groups to add
187  */
188 function wp_cache_add_global_groups( $groups ) {
189         global $wp_object_cache;
190
191         return $wp_object_cache->add_global_groups($groups);
192 }
193
194 /**
195  * Adds a group or set of groups to the list of non-persistent groups.
196  *
197  * @since 2.6.0
198  *
199  * @param string|array $groups A group or an array of groups to add
200  */
201 function wp_cache_add_non_persistent_groups( $groups ) {
202         // Default cache doesn't persist so nothing to do here.
203         return;
204 }
205
206 /**
207  * Reset internal cache keys and structures.  If the cache backend uses global blog or site IDs as part of its cache keys,
208  * this function instructs the backend to reset those keys and perform any cleanup since blog or site IDs have changed since cache init.
209  *
210  * @since 2.6.0
211  */
212 function wp_cache_reset() {
213         global $wp_object_cache;
214
215         return $wp_object_cache->reset();
216 }
217
218 /**
219  * WordPress Object Cache
220  *
221  * The WordPress Object Cache is used to save on trips to the database. The
222  * Object Cache stores all of the cache data to memory and makes the cache
223  * contents available by using a key, which is used to name and later retrieve
224  * the cache contents.
225  *
226  * The Object Cache can be replaced by other caching mechanisms by placing files
227  * in the wp-content folder which is looked at in wp-settings. If that file
228  * exists, then this file will not be included.
229  *
230  * @package WordPress
231  * @subpackage Cache
232  * @since 2.0
233  */
234 class WP_Object_Cache {
235
236         /**
237          * Holds the cached objects
238          *
239          * @var array
240          * @access private
241          * @since 2.0.0
242          */
243         var $cache = array ();
244
245         /**
246          * The amount of times the cache data was already stored in the cache.
247          *
248          * @since 2.5.0
249          * @access private
250          * @var int
251          */
252         var $cache_hits = 0;
253
254         /**
255          * Amount of times the cache did not have the request in cache
256          *
257          * @var int
258          * @access public
259          * @since 2.0.0
260          */
261         var $cache_misses = 0;
262
263         /**
264          * List of global groups
265          *
266          * @var array
267          * @access protected
268          * @since 3.0.0
269          */
270         var $global_groups = array();
271
272         /**
273          * Adds data to the cache if it doesn't already exist.
274          *
275          * @uses WP_Object_Cache::get Checks to see if the cache already has data.
276          * @uses WP_Object_Cache::set Sets the data after the checking the cache
277          *              contents existence.
278          *
279          * @since 2.0.0
280          *
281          * @param int|string $key What to call the contents in the cache
282          * @param mixed $data The contents to store in the cache
283          * @param string $group Where to group the cache contents
284          * @param int $expire When to expire the cache contents
285          * @return bool False if cache key and group already exist, true on success
286          */
287         function add( $key, $data, $group = 'default', $expire = '' ) {
288                 if ( wp_suspend_cache_addition() )
289                         return false;
290
291                 if ( empty ($group) )
292                         $group = 'default';
293
294                 if (false !== $this->get($key, $group))
295                         return false;
296
297                 return $this->set($key, $data, $group, $expire);
298         }
299
300         /**
301          * Sets the list of global groups.
302          *
303          * @since 3.0.0
304          *
305          * @param array $groups List of groups that are global.
306          */
307         function add_global_groups( $groups ) {
308                 $groups = (array) $groups;
309
310                 $this->global_groups = array_merge($this->global_groups, $groups);
311                 $this->global_groups = array_unique($this->global_groups);
312         }
313
314         /**
315          * Decrement numeric cache item's value
316          *
317          * @since 3.3.0
318          *
319          * @param int|string $key The cache key to increment
320          * @param int $offset The amount by which to decrement the item's value.  Default is 1.
321          * @param string $group The group the key is in.
322          * @return false|int False on failure, the item's new value on success.
323          */
324         function decr( $key, $offset = 1, $group = 'default' ) {
325                 if ( ! isset( $this->cache[ $group ][ $key ] ) )
326                         return false;
327
328                 if ( ! is_numeric( $this->cache[ $group ][ $key ] ) )
329                         $this->cache[ $group ][ $key ] = 0;
330
331                 $offset = (int) $offset;
332
333                 $this->cache[ $group ][ $key ] -= $offset;
334
335                 if ( $this->cache[ $group ][ $key ] < 0 )
336                         $this->cache[ $group ][ $key ] = 0;
337
338                 return $this->cache[ $group ][ $key ];
339         }
340
341         /**
342          * Remove the contents of the cache key in the group
343          *
344          * If the cache key does not exist in the group and $force parameter is set
345          * to false, then nothing will happen. The $force parameter is set to false
346          * by default.
347          *
348          * @since 2.0.0
349          *
350          * @param int|string $key What the contents in the cache are called
351          * @param string $group Where the cache contents are grouped
352          * @param bool $force Optional. Whether to force the unsetting of the cache
353          *              key in the group
354          * @return bool False if the contents weren't deleted and true on success
355          */
356         function delete($key, $group = 'default', $force = false) {
357                 if (empty ($group))
358                         $group = 'default';
359
360                 if (!$force && false === $this->get($key, $group))
361                         return false;
362
363                 unset ($this->cache[$group][$key]);
364                 return true;
365         }
366
367         /**
368          * Clears the object cache of all data
369          *
370          * @since 2.0.0
371          *
372          * @return bool Always returns true
373          */
374         function flush() {
375                 $this->cache = array ();
376
377                 return true;
378         }
379
380         /**
381          * Retrieves the cache contents, if it exists
382          *
383          * The contents will be first attempted to be retrieved by searching by the
384          * key in the cache group. If the cache is hit (success) then the contents
385          * are returned.
386          *
387          * On failure, the number of cache misses will be incremented.
388          *
389          * @since 2.0.0
390          *
391          * @param int|string $key What the contents in the cache are called
392          * @param string $group Where the cache contents are grouped
393          * @param string $force Whether to force a refetch rather than relying on the local cache (default is false)
394          * @return bool|mixed False on failure to retrieve contents or the cache
395          *              contents on success
396          */
397         function get( $key, $group = 'default', $force = false) {
398                 if ( empty ($group) )
399                         $group = 'default';
400
401                 if ( isset ($this->cache[$group][$key]) ) {
402                         $this->cache_hits += 1;
403                         if ( is_object($this->cache[$group][$key]) )
404                                 return clone $this->cache[$group][$key];
405                         else
406                                 return $this->cache[$group][$key];
407                 }
408
409                 $this->cache_misses += 1;
410                 return false;
411         }
412
413         /**
414          * Increment numeric cache item's value
415          *
416          * @since 3.3.0
417          *
418          * @param int|string $key The cache key to increment
419          * @param int $offset The amount by which to increment the item's value.  Default is 1.
420          * @param string $group The group the key is in.
421          * @return false|int False on failure, the item's new value on success.
422          */
423         function incr( $key, $offset = 1, $group = 'default' ) {
424                 if ( ! isset( $this->cache[ $group ][ $key ] ) )
425                         return false;
426
427                 if ( ! is_numeric( $this->cache[ $group ][ $key ] ) )
428                         $this->cache[ $group ][ $key ] = 0;
429
430                 $offset = (int) $offset;
431
432                 $this->cache[ $group ][ $key ] += $offset;
433
434                 if ( $this->cache[ $group ][ $key ] < 0 )
435                         $this->cache[ $group ][ $key ] = 0;
436
437                 return $this->cache[ $group ][ $key ];
438         }
439
440         /**
441          * Replace the contents in the cache, if contents already exist
442          *
443          * @since 2.0.0
444          * @see WP_Object_Cache::set()
445          *
446          * @param int|string $key What to call the contents in the cache
447          * @param mixed $data The contents to store in the cache
448          * @param string $group Where to group the cache contents
449          * @param int $expire When to expire the cache contents
450          * @return bool False if not exists, true if contents were replaced
451          */
452         function replace($key, $data, $group = 'default', $expire = '') {
453                 if (empty ($group))
454                         $group = 'default';
455
456                 if ( false === $this->get($key, $group) )
457                         return false;
458
459                 return $this->set($key, $data, $group, $expire);
460         }
461
462         /**
463          * Reset keys
464          *
465          * @since 3.0.0
466          */
467         function reset() {
468                 // Clear out non-global caches since the blog ID has changed.
469                 foreach ( array_keys($this->cache) as $group ) {
470                         if ( !in_array($group, $this->global_groups) )
471                                 unset($this->cache[$group]);
472                 }
473         }
474
475         /**
476          * Sets the data contents into the cache
477          *
478          * The cache contents is grouped by the $group parameter followed by the
479          * $key. This allows for duplicate ids in unique groups. Therefore, naming of
480          * the group should be used with care and should follow normal function
481          * naming guidelines outside of core WordPress usage.
482          *
483          * The $expire parameter is not used, because the cache will automatically
484          * expire for each time a page is accessed and PHP finishes. The method is
485          * more for cache plugins which use files.
486          *
487          * @since 2.0.0
488          *
489          * @param int|string $key What to call the contents in the cache
490          * @param mixed $data The contents to store in the cache
491          * @param string $group Where to group the cache contents
492          * @param int $expire Not Used
493          * @return bool Always returns true
494          */
495         function set($key, $data, $group = 'default', $expire = '') {
496                 if ( empty ($group) )
497                         $group = 'default';
498
499                 if ( NULL === $data )
500                         $data = '';
501
502                 if ( is_object($data) )
503                         $data = clone $data;
504
505                 $this->cache[$group][$key] = $data;
506                 return true;
507         }
508
509         /**
510          * Echoes the stats of the caching.
511          *
512          * Gives the cache hits, and cache misses. Also prints every cached group,
513          * key and the data.
514          *
515          * @since 2.0.0
516          */
517         function stats() {
518                 echo "<p>";
519                 echo "<strong>Cache Hits:</strong> {$this->cache_hits}<br />";
520                 echo "<strong>Cache Misses:</strong> {$this->cache_misses}<br />";
521                 echo "</p>";
522                 echo '<ul>';
523                 foreach ($this->cache as $group => $cache) {
524                         echo "<li><strong>Group:</strong> $group - ( " . number_format( strlen( serialize( $cache ) ) / 1024, 2 ) . 'k )</li>';
525                 }
526                 echo '</ul>';
527         }
528
529         /**
530          * Sets up object properties; PHP 5 style constructor
531          *
532          * @since 2.0.8
533          * @return null|WP_Object_Cache If cache is disabled, returns null.
534          */
535         function __construct() {
536                 /**
537                  * @todo This should be moved to the PHP4 style constructor, PHP5
538                  * already calls __destruct()
539                  */
540                 register_shutdown_function(array(&$this, "__destruct"));
541         }
542
543         /**
544          * Will save the object cache before object is completely destroyed.
545          *
546          * Called upon object destruction, which should be when PHP ends.
547          *
548          * @since  2.0.8
549          *
550          * @return bool True value. Won't be used by PHP
551          */
552         function __destruct() {
553                 return true;
554         }
555 }
556 ?>