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