]> scripts.mit.edu Git - autoinstalls/wordpress.git/blob - wp-includes/cache.php
Wordpress 2.8-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 $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         // 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.0
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.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.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.0
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.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.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.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.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.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                         if ( is_object($this->cache[$group][$id]) )
317                                 return wp_clone($this->cache[$group][$id]);
318                         else
319                                 return $this->cache[$group][$id];
320                 }
321
322                 if ( isset ($this->non_existant_objects[$group][$id]) )
323                         return false;
324
325                 $this->non_existant_objects[$group][$id] = true;
326                 $this->cache_misses += 1;
327                 return false;
328         }
329
330         /**
331          * Replace the contents in the cache, if contents already exist
332          *
333          * @since 2.0.0
334          * @see WP_Object_Cache::set()
335          *
336          * @param int|string $id What to call the contents in the cache
337          * @param mixed $data The contents to store in the cache
338          * @param string $group Where to group the cache contents
339          * @param int $expire When to expire the cache contents
340          * @return bool False if not exists, true if contents were replaced
341          */
342         function replace($id, $data, $group = 'default', $expire = '') {
343                 if (empty ($group))
344                         $group = 'default';
345
346                 if (false === $this->get($id, $group, false))
347                         return false;
348
349                 return $this->set($id, $data, $group, $expire);
350         }
351
352         /**
353          * Sets the data contents into the cache
354          *
355          * The cache contents is grouped by the $group parameter followed by the
356          * $id. This allows for duplicate ids in unique groups. Therefore, naming of
357          * the group should be used with care and should follow normal function
358          * naming guidelines outside of core WordPress usage.
359          *
360          * The $expire parameter is not used, because the cache will automatically
361          * expire for each time a page is accessed and PHP finishes. The method is
362          * more for cache plugins which use files.
363          *
364          * @since 2.0.0
365          *
366          * @param int|string $id What to call the contents in the cache
367          * @param mixed $data The contents to store in the cache
368          * @param string $group Where to group the cache contents
369          * @param int $expire Not Used
370          * @return bool Always returns true
371          */
372         function set($id, $data, $group = 'default', $expire = '') {
373                 if (empty ($group))
374                         $group = 'default';
375
376                 if (NULL === $data)
377                         $data = '';
378
379                 if ( is_object($data) )
380                         $data = wp_clone($data);
381
382                 $this->cache[$group][$id] = $data;
383
384                 if(isset($this->non_existant_objects[$group][$id]))
385                         unset ($this->non_existant_objects[$group][$id]);
386
387                 return true;
388         }
389
390         /**
391          * Echos the stats of the caching.
392          *
393          * Gives the cache hits, and cache misses. Also prints every cached group,
394          * key and the data.
395          *
396          * @since 2.0.0
397          */
398         function stats() {
399                 echo "<p>";
400                 echo "<strong>Cache Hits:</strong> {$this->cache_hits}<br />";
401                 echo "<strong>Cache Misses:</strong> {$this->cache_misses}<br />";
402                 echo "</p>";
403
404                 foreach ($this->cache as $group => $cache) {
405                         echo "<p>";
406                         echo "<strong>Group:</strong> $group<br />";
407                         echo "<strong>Cache:</strong>";
408                         echo "<pre>";
409                         print_r($cache);
410                         echo "</pre>";
411                 }
412         }
413
414         /**
415          * PHP4 constructor; Calls PHP 5 style constructor
416          *
417          * @since 2.0.0
418          *
419          * @return WP_Object_Cache
420          */
421         function WP_Object_Cache() {
422                 return $this->__construct();
423         }
424
425         /**
426          * Sets up object properties; PHP 5 style constructor
427          *
428          * @since 2.0.8
429          * @return null|WP_Object_Cache If cache is disabled, returns null.
430          */
431         function __construct() {
432                 /**
433                  * @todo This should be moved to the PHP4 style constructor, PHP5
434                  * already calls __destruct()
435                  */
436                 register_shutdown_function(array(&$this, "__destruct"));
437         }
438
439         /**
440          * Will save the object cache before object is completely destroyed.
441          *
442          * Called upon object destruction, which should be when PHP ends.
443          *
444          * @since  2.0.8
445          *
446          * @return bool True value. Won't be used by PHP
447          */
448         function __destruct() {
449                 return true;
450         }
451 }
452 ?>