Wordpress 3.2-scripts
[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 $key 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 $key 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 function wp_cache_reset() {
176         global $wp_object_cache;
177
178         return $wp_object_cache->reset();
179 }
180
181 /**
182  * WordPress Object Cache
183  *
184  * The WordPress Object Cache is used to save on trips to the database. The
185  * Object Cache stores all of the cache data to memory and makes the cache
186  * contents available by using a key, which is used to name and later retrieve
187  * the cache contents.
188  *
189  * The Object Cache can be replaced by other caching mechanisms by placing files
190  * in the wp-content folder which is looked at in wp-settings. If that file
191  * exists, then this file will not be included.
192  *
193  * @package WordPress
194  * @subpackage Cache
195  * @since 2.0
196  */
197 class WP_Object_Cache {
198
199         /**
200          * Holds the cached objects
201          *
202          * @var array
203          * @access private
204          * @since 2.0.0
205          */
206         var $cache = array ();
207
208         /**
209          * Cache objects that do not exist in the cache
210          *
211          * @var array
212          * @access private
213          * @since 2.0.0
214          */
215         var $non_existent_objects = array ();
216
217         /**
218          * The amount of times the cache data was already stored in the cache.
219          *
220          * @since 2.5.0
221          * @access private
222          * @var int
223          */
224         var $cache_hits = 0;
225
226         /**
227          * Amount of times the cache did not have the request in cache
228          *
229          * @var int
230          * @access public
231          * @since 2.0.0
232          */
233         var $cache_misses = 0;
234
235         /**
236          * List of global groups
237          *
238          * @var array
239          * @access protected
240          * @since 3.0.0
241          */
242         var $global_groups = array();
243
244         /**
245          * Adds data to the cache if it doesn't already exist.
246          *
247          * @uses WP_Object_Cache::get Checks to see if the cache already has data.
248          * @uses WP_Object_Cache::set Sets the data after the checking the cache
249          *              contents existance.
250          *
251          * @since 2.0.0
252          *
253          * @param int|string $id What to call the contents in the cache
254          * @param mixed $data The contents to store in the cache
255          * @param string $group Where to group the cache contents
256          * @param int $expire When to expire the cache contents
257          * @return bool False if cache ID and group already exists, true on success
258          */
259         function add( $id, $data, $group = 'default', $expire = '' ) {
260                 if ( empty ($group) )
261                         $group = 'default';
262
263                 if (false !== $this->get($id, $group))
264                         return false;
265
266                 return $this->set($id, $data, $group, $expire);
267         }
268
269         /**
270          * Sets the list of global groups.
271          *
272          * @since 3.0.0
273          *
274          * @param array $groups List of groups that are global.
275          */
276         function add_global_groups( $groups ) {
277                 $groups = (array) $groups;
278
279                 $this->global_groups = array_merge($this->global_groups, $groups);
280                 $this->global_groups = array_unique($this->global_groups);
281         }
282
283         /**
284          * Remove the contents of the cache ID in the group
285          *
286          * If the cache ID does not exist in the group and $force parameter is set
287          * to false, then nothing will happen. The $force parameter is set to false
288          * by default.
289          *
290          * On success the group and the id will be added to the
291          * $non_existent_objects property in the class.
292          *
293          * @since 2.0.0
294          *
295          * @param int|string $id What the contents in the cache are called
296          * @param string $group Where the cache contents are grouped
297          * @param bool $force Optional. Whether to force the unsetting of the cache
298          *              ID in the group
299          * @return bool False if the contents weren't deleted and true on success
300          */
301         function delete($id, $group = 'default', $force = false) {
302                 if (empty ($group))
303                         $group = 'default';
304
305                 if (!$force && false === $this->get($id, $group))
306                         return false;
307
308                 unset ($this->cache[$group][$id]);
309                 $this->non_existent_objects[$group][$id] = true;
310                 return true;
311         }
312
313         /**
314          * Clears the object cache of all data
315          *
316          * @since 2.0.0
317          *
318          * @return bool Always returns true
319          */
320         function flush() {
321                 $this->cache = array ();
322
323                 return true;
324         }
325
326         /**
327          * Retrieves the cache contents, if it exists
328          *
329          * The contents will be first attempted to be retrieved by searching by the
330          * ID in the cache group. If the cache is hit (success) then the contents
331          * are returned.
332          *
333          * On failure, the $non_existent_objects property is checked and if the
334          * cache group and ID exist in there the cache misses will not be
335          * incremented. If not in the nonexistent objects property, then the cache
336          * misses will be incremented and the cache group and ID will be added to
337          * the nonexistent objects.
338          *
339          * @since 2.0.0
340          *
341          * @param int|string $id What the contents in the cache are called
342          * @param string $group Where the cache contents are grouped
343          * @return bool|mixed False on failure to retrieve contents or the cache
344          *              contents on success
345          */
346         function get($id, $group = 'default') {
347                 if ( empty ($group) )
348                         $group = 'default';
349
350                 if ( isset ($this->cache[$group][$id]) ) {
351                         $this->cache_hits += 1;
352                         if ( is_object($this->cache[$group][$id]) )
353                                 return clone $this->cache[$group][$id];
354                         else
355                                 return $this->cache[$group][$id];
356                 }
357
358                 if ( isset ($this->non_existent_objects[$group][$id]) )
359                         return false;
360
361                 $this->non_existent_objects[$group][$id] = true;
362                 $this->cache_misses += 1;
363                 return false;
364         }
365
366         /**
367          * Replace the contents in the cache, if contents already exist
368          *
369          * @since 2.0.0
370          * @see WP_Object_Cache::set()
371          *
372          * @param int|string $id What to call the contents in the cache
373          * @param mixed $data The contents to store in the cache
374          * @param string $group Where to group the cache contents
375          * @param int $expire When to expire the cache contents
376          * @return bool False if not exists, true if contents were replaced
377          */
378         function replace($id, $data, $group = 'default', $expire = '') {
379                 if (empty ($group))
380                         $group = 'default';
381
382                 if ( false === $this->get($id, $group) )
383                         return false;
384
385                 return $this->set($id, $data, $group, $expire);
386         }
387
388         /**
389          * Reset keys
390          *
391          * @since 3.0.0
392          */
393         function reset() {
394                 // Clear out non-global caches since the blog ID has changed.
395                 foreach ( array_keys($this->cache) as $group ) {
396                         if ( !in_array($group, $this->global_groups) )
397                                 unset($this->cache[$group]);
398                 }
399         }
400
401         /**
402          * Sets the data contents into the cache
403          *
404          * The cache contents is grouped by the $group parameter followed by the
405          * $id. This allows for duplicate ids in unique groups. Therefore, naming of
406          * the group should be used with care and should follow normal function
407          * naming guidelines outside of core WordPress usage.
408          *
409          * The $expire parameter is not used, because the cache will automatically
410          * expire for each time a page is accessed and PHP finishes. The method is
411          * more for cache plugins which use files.
412          *
413          * @since 2.0.0
414          *
415          * @param int|string $id What to call the contents in the cache
416          * @param mixed $data The contents to store in the cache
417          * @param string $group Where to group the cache contents
418          * @param int $expire Not Used
419          * @return bool Always returns true
420          */
421         function set($id, $data, $group = 'default', $expire = '') {
422                 if ( empty ($group) )
423                         $group = 'default';
424
425                 if ( NULL === $data )
426                         $data = '';
427
428                 if ( is_object($data) )
429                         $data = clone $data;
430
431                 $this->cache[$group][$id] = $data;
432
433                 if ( isset($this->non_existent_objects[$group][$id]) )
434                         unset ($this->non_existent_objects[$group][$id]);
435
436                 return true;
437         }
438
439         /**
440          * Echoes the stats of the caching.
441          *
442          * Gives the cache hits, and cache misses. Also prints every cached group,
443          * key and the data.
444          *
445          * @since 2.0.0
446          */
447         function stats() {
448                 echo "<p>";
449                 echo "<strong>Cache Hits:</strong> {$this->cache_hits}<br />";
450                 echo "<strong>Cache Misses:</strong> {$this->cache_misses}<br />";
451                 echo "</p>";
452                 echo '<ul>';
453                 foreach ($this->cache as $group => $cache) {
454                         echo "<li><strong>Group:</strong> $group - ( " . number_format( strlen( serialize( $cache ) ) / 1024, 2 ) . 'k )</li>';
455                 }
456                 echo '</ul>';
457         }
458
459         /**
460          * Sets up object properties; PHP 5 style constructor
461          *
462          * @since 2.0.8
463          * @return null|WP_Object_Cache If cache is disabled, returns null.
464          */
465         function __construct() {
466                 /**
467                  * @todo This should be moved to the PHP4 style constructor, PHP5
468                  * already calls __destruct()
469                  */
470                 register_shutdown_function(array(&$this, "__destruct"));
471         }
472
473         /**
474          * Will save the object cache before object is completely destroyed.
475          *
476          * Called upon object destruction, which should be when PHP ends.
477          *
478          * @since  2.0.8
479          *
480          * @return bool True value. Won't be used by PHP
481          */
482         function __destruct() {
483                 return true;
484         }
485 }
486 ?>