Make WordPress Core

Ticket #5511: cache.phpdoc.r6542.diff

File cache.phpdoc.r6542.diff, 10.8 KB (added by darkdragon, 16 years ago)

Complete phpdoc documentation for cache.php based off of r6542

  • cache.php

     
    11<?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 */
    222function wp_cache_add($key, $data, $flag = '', $expire = 0) {
    323        global $wp_object_cache;
    424
    525        return $wp_object_cache->add($key, $data, $flag, $expire);
    626}
    727
     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 */
    839function wp_cache_close() {
    940        return true;
    1041}
    1142
     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 */
    1254function wp_cache_delete($id, $flag = '') {
    1355        global $wp_object_cache;
    1456
    1557        return $wp_object_cache->delete($id, $flag);
    1658}
    1759
     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 */
    1869function wp_cache_flush() {
    1970        global $wp_object_cache;
    2071
    2172        return $wp_object_cache->flush();
    2273}
    2374
     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 */
    2486function wp_cache_get($id, $flag = '') {
    2587        global $wp_object_cache;
    2688
    2789        return $wp_object_cache->get($id, $flag);
    2890}
    2991
     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 */
    3098function wp_cache_init() {
    3199        $GLOBALS['wp_object_cache'] =& new WP_Object_Cache();
    32100}
    33101
     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 */
    34115function wp_cache_replace($key, $data, $flag = '', $expire = 0) {
    35116        global $wp_object_cache;
    36117
    37118        return $wp_object_cache->replace($key, $data, $flag, $expire);
    38119}
    39120
     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 */
    40134function wp_cache_set($key, $data, $flag = '', $expire = 0) {
    41135        global $wp_object_cache;
    42136
    43137        return $wp_object_cache->set($key, $data, $flag, $expire);
    44138}
    45139
     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 */
    46156class WP_Object_Cache {
     157
     158        /**
     159         * Holds the cached objects
     160         *
     161         * @var array
     162         * @access private
     163         * @since 2.0
     164         */
    47165        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         */
    48174        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         */
    49183        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         */
    50192        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         */
    51201        var $cache_misses = 0;
    52202
     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         */
    53217        function add($id, $data, $group = 'default', $expire = '') {
    54218                if (empty ($group))
    55219                        $group = 'default';
     
    60224                return $this->set($id, $data, $group, $expire);
    61225        }
    62226
     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         */
    63244        function delete($id, $group = 'default', $force = false) {
    64245                if (empty ($group))
    65246                        $group = 'default';
     
    72253                return true;
    73254        }
    74255
     256        /**
     257         * Clears the object cache of all data
     258         *
     259         * @since 2.0
     260         *
     261         * @return bool Always returns true
     262         */
    75263        function flush() {
    76264                $this->cache = array ();
    77265
    78266                return true;
    79267        }
    80268
     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         */
    81288        function get($id, $group = 'default') {
    82289                if (empty ($group))
    83290                        $group = 'default';
     
    95302                return false;
    96303        }
    97304
     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         */
    98317        function replace($id, $data, $group = 'default', $expire = '') {
    99318                if (empty ($group))
    100319                        $group = 'default';
     
    105324                return $this->set($id, $data, $group, $expire);
    106325        }
    107326
     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         */
    108348        function set($id, $data, $group = 'default', $expire = '') {
    109349                if (empty ($group))
    110350                        $group = 'default';
     
    118358                return true;
    119359        }
    120360
     361        /**
     362         * Echos the stats of the caching.
     363         *
     364         * Gives the cache hits, and cache misses. Also prints every cached
     365         * group, key and the data.
     366         *
     367         * @since 2.0
     368         */
    121369        function stats() {
    122370                echo "<p>";
    123371                echo "<strong>Cache Hits:</strong> {$this->cache_hits}<br />";
     
    134382                }
    135383        }
    136384
     385        /**
     386         * PHP4 constructor; Calls PHP 5 style constructor
     387         *
     388         * @since 2.0
     389         *
     390         * @return WP_Object_Cache
     391         */
    137392        function WP_Object_Cache() {
    138393                return $this->__construct();
    139394        }
    140395
     396        /**
     397         * Sets up object properties; PHP 5 style constructor
     398         *
     399         * @since 2.0.8
     400         * @return null|WP_Object_Cache If cache is disabled, returns null.
     401         */
    141402        function __construct() {
    142                 register_shutdown_function(array(&$this, "__destruct"));
     403                register_shutdown_function(array(&$this, "__destruct")); /** @todo This should be moved to the PHP4 style constructor, PHP5 already calls __destruct() */
    143404        }
    144405
     406        /**
     407         * Will save the object cache before object is completely destroyed.
     408         *
     409         * Called upon object destruction, which should be when PHP ends.
     410         *
     411         * @since  2.0.8
     412         *
     413         * @return bool True value. Won't be used by PHP
     414         */
    145415        function __destruct() {
    146416                return true;
    147417        }