Ticket #5511: cache.phpdoc.r6542.diff

File cache.phpdoc.r6542.diff, 10.8 kB (added by darkdragon, 8 months ago)

Complete phpdoc documentation for cache.php based off of r6542

  • cache.php

    old new  
    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        }