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