Wordpress 2.5.1-scripts
[autoinstalls/wordpress.git] / wp-includes / cache.php
1 <?php
2 /**
3  * Object Cache API
4  *
5  * @package WordPress
6  * @subpackage Cache
7  */
8
9 /**
10  * wp_cache_add() - Adds data to the cache, if the cache key doesn't aleady exist
11  *
12  * @since 2.0
13  * @uses $wp_object_cache Object Cache Class
14  * @see WP_Object_Cache::add()
15  *
16  * @param int|string $key The cache ID to use for retrieval later
17  * @param mixed $data The data to add to the cache store
18  * @param string $flag The group to add the cache to
19  * @param int $expire When the cache data should be expired
20  * @return unknown
21  */
22 function wp_cache_add($key, $data, $flag = '', $expire = 0) {
23         global $wp_object_cache;
24
25         return $wp_object_cache->add($key, $data, $flag, $expire);
26 }
27
28 /**
29  * wp_cache_close() - Closes the cache
30  *
31  * This function has ceased to do anything since WordPress 2.5.
32  * The functionality was removed along with the rest of the
33  * persistant cache.
34  *
35  * @since 2.0
36  *
37  * @return bool Always returns True
38  */
39 function wp_cache_close() {
40         return true;
41 }
42
43 /**
44  * wp_cache_delete() - Removes the cache contents matching ID and flag
45  *
46  * @since 2.0
47  * @uses $wp_object_cache Object Cache Class
48  * @see WP_Object_Cache::delete()
49  *
50  * @param int|string $id What the contents in the cache are called
51  * @param string $flag Where the cache contents are grouped
52  * @return bool True on successful removal, false on failure
53  */
54 function wp_cache_delete($id, $flag = '') {
55         global $wp_object_cache;
56
57         return $wp_object_cache->delete($id, $flag);
58 }
59
60 /**
61  * wp_cache_flush() - Removes all cache items
62  *
63  * @since 2.0
64  * @uses $wp_object_cache Object Cache Class
65  * @see WP_Object_Cache::flush()
66  *
67  * @return bool Always returns true
68  */
69 function wp_cache_flush() {
70         global $wp_object_cache;
71
72         return $wp_object_cache->flush();
73 }
74
75 /**
76  * wp_cache_get() - Retrieves the cache contents from the cache by ID and flag
77  *
78  * @since 2.0
79  * @uses $wp_object_cache Object Cache Class
80  * @see WP_Object_Cache::get()
81  *
82  * @param int|string $id What the contents in the cache are called
83  * @param string $flag Where the cache contents are grouped
84  * @return bool|mixed False on failure to retrieve contents or the cache contents on success
85  */
86 function wp_cache_get($id, $flag = '') {
87         global $wp_object_cache;
88
89         return $wp_object_cache->get($id, $flag);
90 }
91
92 /**
93  * wp_cache_init() - Sets up Object Cache Global and assigns it
94  *
95  * @since 2.0
96  * @global WP_Object_Cache $wp_object_cache WordPress Object Cache
97  */
98 function wp_cache_init() {
99         $GLOBALS['wp_object_cache'] =& new WP_Object_Cache();
100 }
101
102 /**
103  * wp_cache_replace() - Replaces the contents of the cache with new data
104  *
105  * @since 2.0
106  * @uses $wp_object_cache Object Cache Class
107  * @see WP_Object_Cache::replace()
108  *
109  * @param int|string $id What to call the contents in the cache
110  * @param mixed $data The contents to store in the cache
111  * @param string $flag Where to group the cache contents
112  * @param int $expire When to expire the cache contents
113  * @return bool False if cache ID and group already exists, true on success
114  */
115 function wp_cache_replace($key, $data, $flag = '', $expire = 0) {
116         global $wp_object_cache;
117
118         return $wp_object_cache->replace($key, $data, $flag, $expire);
119 }
120
121 /**
122  * wp_cache_set() - Saves the data to the cache
123  *
124  * @since 2.0
125  * @uses $wp_object_cache Object Cache Class
126  * @see WP_Object_Cache::set()
127  *
128  * @param int|string $id What to call the contents in the cache
129  * @param mixed $data The contents to store in the cache
130  * @param string $flag Where to group the cache contents
131  * @param int $expire When to expire the cache contents
132  * @return bool False if cache ID and group already exists, true on success
133  */
134 function wp_cache_set($key, $data, $flag = '', $expire = 0) {
135         global $wp_object_cache;
136
137         return $wp_object_cache->set($key, $data, $flag, $expire);
138 }
139
140 /**
141  * WordPress Object Cache
142  *
143  * The WordPress Object Cache is used to save on trips to the database.
144  * The Object Cache stores all of the cache data to memory and makes the
145  * cache contents available by using a key, which is used to name and
146  * later retrieve the cache contents.
147  *
148  * The Object Cache can be replaced by other caching mechanisms by placing
149  * files in the wp-content folder which is looked at in wp-settings. If
150  * that file exists, then this file will not be included.
151  *
152  * @package WordPress
153  * @subpackage Cache
154  * @since 2.0
155  */
156 class WP_Object_Cache {
157
158         /**
159          * Holds the cached objects
160          *
161          * @var array
162          * @access private
163          * @since 2.0
164          */
165         var $cache = array ();
166
167         /**
168          * Cache objects that do not exist in the cache
169          *
170          * @var array
171          * @access private
172          * @since 2.0
173          */
174         var $non_existant_objects = array ();
175
176         /**
177          * Object caches that are global
178          *
179          * @var array
180          * @access private
181          * @since 2.0
182          */
183         var $global_groups = array ('users', 'userlogins', 'usermeta');
184
185         /**
186          * The amount of times the cache data was already stored in the cache.
187          *
188          * @since 2.5
189          * @access private
190          * @var int
191          */
192         var $cache_hits = 0;
193
194         /**
195          * Amount of times the cache did not have the request in cache
196          *
197          * @var int
198          * @access public
199          * @since 2.0
200          */
201         var $cache_misses = 0;
202
203         /**
204          * Adds data to the cache if it doesn't already exist.
205          *
206          * @uses WP_Object_Cache::get Checks to see if the cache already has data.
207          * @uses WP_Object_Cache::set Sets the data after the checking the cache contents existance.
208          *
209          * @since 2.0
210          *
211          * @param int|string $id What to call the contents in the cache
212          * @param mixed $data The contents to store in the cache
213          * @param string $group Where to group the cache contents
214          * @param int $expire When to expire the cache contents
215          * @return bool False if cache ID and group already exists, true on success
216          */
217         function add($id, $data, $group = 'default', $expire = '') {
218                 if (empty ($group))
219                         $group = 'default';
220
221                 if (false !== $this->get($id, $group, false))
222                         return false;
223
224                 return $this->set($id, $data, $group, $expire);
225         }
226
227         /**
228          * Remove the contents of the cache ID in the group
229          *
230          * If the cache ID does not exist in the group and $force parameter
231          * is set to false, then nothing will happen. The $force parameter
232          * is set to false by default.
233          *
234          * On success the group and the id will be added to the
235          * $non_existant_objects property in the class.
236          *
237          * @since 2.0
238          *
239          * @param int|string $id What the contents in the cache are called
240          * @param string $group Where the cache contents are grouped
241          * @param bool $force Optional. Whether to force the unsetting of the cache ID in the group
242          * @return bool False if the contents weren't deleted and true on success
243          */
244         function delete($id, $group = 'default', $force = false) {
245                 if (empty ($group))
246                         $group = 'default';
247
248                 if (!$force && false === $this->get($id, $group, false))
249                         return false;
250
251                 unset ($this->cache[$group][$id]);
252                 $this->non_existant_objects[$group][$id] = true;
253                 return true;
254         }
255
256         /**
257          * Clears the object cache of all data
258          *
259          * @since 2.0
260          *
261          * @return bool Always returns true
262          */
263         function flush() {
264                 $this->cache = array ();
265
266                 return true;
267         }
268
269         /**
270          * Retrieves the cache contents, if it exists
271          *
272          * The contents will be first attempted to be retrieved by searching
273          * by the ID in the cache group. If the cache is hit (success) then
274          * the contents are returned.
275          *
276          * On failure, the $non_existant_objects property is checked and if
277          * the cache group and ID exist in there the cache misses will not be
278          * incremented. If not in the nonexistant objects property, then the
279          * cache misses will be incremented and the cache group and ID will
280          * be added to the nonexistant objects.
281          *
282          * @since 2.0
283          *
284          * @param int|string $id What the contents in the cache are called
285          * @param string $group Where the cache contents are grouped
286          * @return bool|mixed False on failure to retrieve contents or the cache contents on success
287          */
288         function get($id, $group = 'default') {
289                 if (empty ($group))
290                         $group = 'default';
291
292                 if (isset ($this->cache[$group][$id])) {
293                         $this->cache_hits += 1;
294                         return $this->cache[$group][$id];
295                 }
296
297                 if ( isset ($this->non_existant_objects[$group][$id]) )
298                         return false;
299
300                 $this->non_existant_objects[$group][$id] = true;
301                 $this->cache_misses += 1;
302                 return false;
303         }
304
305         /**
306          * Replace the contents in the cache, if contents already exist
307          *
308          * @since 2.0
309          * @see WP_Object_Cache::set()
310          *
311          * @param int|string $id What to call the contents in the cache
312          * @param mixed $data The contents to store in the cache
313          * @param string $group Where to group the cache contents
314          * @param int $expire When to expire the cache contents
315          * @return bool False if not exists, true if contents were replaced
316          */
317         function replace($id, $data, $group = 'default', $expire = '') {
318                 if (empty ($group))
319                         $group = 'default';
320
321                 if (false === $this->get($id, $group, false))
322                         return false;
323
324                 return $this->set($id, $data, $group, $expire);
325         }
326
327         /**
328          * Sets the data contents into the cache
329          *
330          * The cache contents is grouped by the $group parameter followed
331          * by the $id. This allows for duplicate ids in unique groups.
332          * Therefore, naming of the group should be used with care and
333          * should follow normal function naming guidelines outside of
334          * core WordPress usage.
335          *
336          * The $expire parameter is not used, because the cache will
337          * automatically expire for each time a page is accessed and PHP
338          * finishes. The method is more for cache plugins which use files.
339          *
340          * @since 2.0
341          *
342          * @param int|string $id What to call the contents in the cache
343          * @param mixed $data The contents to store in the cache
344          * @param string $group Where to group the cache contents
345          * @param int $expire Not Used
346          * @return bool Always returns true
347          */
348         function set($id, $data, $group = 'default', $expire = '') {
349                 if (empty ($group))
350                         $group = 'default';
351
352                 if (NULL === $data)
353                         $data = '';
354
355                 $this->cache[$group][$id] = $data;
356
357                 if(isset($this->non_existant_objects[$group][$id]))
358                         unset ($this->non_existant_objects[$group][$id]);
359
360                 return true;
361         }
362
363         /**
364          * Echos the stats of the caching.
365          *
366          * Gives the cache hits, and cache misses. Also prints every cached
367          * group, key and the data.
368          *
369          * @since 2.0
370          */
371         function stats() {
372                 echo "<p>";
373                 echo "<strong>Cache Hits:</strong> {$this->cache_hits}<br />";
374                 echo "<strong>Cache Misses:</strong> {$this->cache_misses}<br />";
375                 echo "</p>";
376
377                 foreach ($this->cache as $group => $cache) {
378                         echo "<p>";
379                         echo "<strong>Group:</strong> $group<br />";
380                         echo "<strong>Cache:</strong>";
381                         echo "<pre>";
382                         print_r($cache);
383                         echo "</pre>";
384                 }
385         }
386
387         /**
388          * PHP4 constructor; Calls PHP 5 style constructor
389          *
390          * @since 2.0
391          *
392          * @return WP_Object_Cache
393          */
394         function WP_Object_Cache() {
395                 return $this->__construct();
396         }
397
398         /**
399          * Sets up object properties; PHP 5 style constructor
400          *
401          * @since 2.0.8
402          * @return null|WP_Object_Cache If cache is disabled, returns null.
403          */
404         function __construct() {
405                 register_shutdown_function(array(&$this, "__destruct")); /** @todo This should be moved to the PHP4 style constructor, PHP5 already calls __destruct() */
406         }
407
408         /**
409          * Will save the object cache before object is completely destroyed.
410          *
411          * Called upon object destruction, which should be when PHP ends.
412          *
413          * @since  2.0.8
414          *
415          * @return bool True value. Won't be used by PHP
416          */
417         function __destruct() {
418                 return true;
419         }
420 }
421 ?>