WP_Object_Cache

Core class that implements an object cache.

Defined (1)

The class is defined in the following location(s).

/wp-includes/cache.php  
  1. class WP_Object_Cache { 
  2.  
  3. /** 
  4. * Holds the cached objects. 
  5. * @since 2.0.0 
  6. * @access private 
  7. * @var array 
  8. */ 
  9. private $cache = array(); 
  10.  
  11. /** 
  12. * The amount of times the cache data was already stored in the cache. 
  13. * @since 2.5.0 
  14. * @access public 
  15. * @var int 
  16. */ 
  17. public $cache_hits = 0; 
  18.  
  19. /** 
  20. * Amount of times the cache did not have the request in cache. 
  21. * @since 2.0.0 
  22. * @access public 
  23. * @var int 
  24. */ 
  25. public $cache_misses = 0; 
  26.  
  27. /** 
  28. * List of global cache groups. 
  29. * @since 3.0.0 
  30. * @access protected 
  31. * @var array 
  32. */ 
  33. protected $global_groups = array(); 
  34.  
  35. /** 
  36. * The blog prefix to prepend to keys in non-global groups. 
  37. * @since 3.5.0 
  38. * @access private 
  39. * @var int 
  40. */ 
  41. private $blog_prefix; 
  42.  
  43. /** 
  44. * Holds the value of is_multisite(). 
  45. * @since 3.5.0 
  46. * @access private 
  47. * @var bool 
  48. */ 
  49. private $multisite; 
  50.  
  51. /** 
  52. * Makes private properties readable for backward compatibility. 
  53. * @since 4.0.0 
  54. * @access public 
  55. * @param string $name Property to get. 
  56. * @return mixed Property. 
  57. */ 
  58. public function __get( $name ) { 
  59. return $this->$name; 
  60.  
  61. /** 
  62. * Makes private properties settable for backward compatibility. 
  63. * @since 4.0.0 
  64. * @access public 
  65. * @param string $name Property to set. 
  66. * @param mixed $value Property value. 
  67. * @return mixed Newly-set property. 
  68. */ 
  69. public function __set( $name, $value ) { 
  70. return $this->$name = $value; 
  71.  
  72. /** 
  73. * Makes private properties checkable for backward compatibility. 
  74. * @since 4.0.0 
  75. * @access public 
  76. * @param string $name Property to check if set. 
  77. * @return bool Whether the property is set. 
  78. */ 
  79. public function __isset( $name ) { 
  80. return isset( $this->$name ); 
  81.  
  82. /** 
  83. * Makes private properties un-settable for backward compatibility. 
  84. * @since 4.0.0 
  85. * @access public 
  86. * @param string $name Property to unset. 
  87. */ 
  88. public function __unset( $name ) { 
  89. unset( $this->$name ); 
  90.  
  91. /** 
  92. * Adds data to the cache if it doesn't already exist. 
  93. * @since 2.0.0 
  94. * @access public 
  95. * @uses WP_Object_Cache::_exists() Checks to see if the cache already has data. 
  96. * @uses WP_Object_Cache::set() Sets the data after the checking the cache 
  97. * contents existence. 
  98. * @param int|string $key What to call the contents in the cache. 
  99. * @param mixed $data The contents to store in the cache. 
  100. * @param string $group Optional. Where to group the cache contents. Default 'default'. 
  101. * @param int $expire Optional. When to expire the cache contents. Default 0 (no expiration). 
  102. * @return bool False if cache key and group already exist, true on success 
  103. */ 
  104. public function add( $key, $data, $group = 'default', $expire = 0 ) { 
  105. if ( wp_suspend_cache_addition() ) 
  106. return false; 
  107.  
  108. if ( empty( $group ) ) 
  109. $group = 'default'; 
  110.  
  111. $id = $key; 
  112. if ( $this->multisite && ! isset( $this->global_groups[ $group ] ) ) 
  113. $id = $this->blog_prefix . $key; 
  114.  
  115. if ( $this->_exists( $id, $group ) ) 
  116. return false; 
  117.  
  118. return $this->set( $key, $data, $group, (int) $expire ); 
  119.  
  120. /** 
  121. * Sets the list of global cache groups. 
  122. * @since 3.0.0 
  123. * @access public 
  124. * @param array $groups List of groups that are global. 
  125. */ 
  126. public function add_global_groups( $groups ) { 
  127. $groups = (array) $groups; 
  128.  
  129. $groups = array_fill_keys( $groups, true ); 
  130. $this->global_groups = array_merge( $this->global_groups, $groups ); 
  131.  
  132. /** 
  133. * Decrements numeric cache item's value. 
  134. * @since 3.3.0 
  135. * @access public 
  136. * @param int|string $key The cache key to decrement. 
  137. * @param int $offset Optional. The amount by which to decrement the item's value. Default 1. 
  138. * @param string $group Optional. The group the key is in. Default 'default'. 
  139. * @return false|int False on failure, the item's new value on success. 
  140. */ 
  141. public function decr( $key, $offset = 1, $group = 'default' ) { 
  142. if ( empty( $group ) ) 
  143. $group = 'default'; 
  144.  
  145. if ( $this->multisite && ! isset( $this->global_groups[ $group ] ) ) 
  146. $key = $this->blog_prefix . $key; 
  147.  
  148. if ( ! $this->_exists( $key, $group ) ) 
  149. return false; 
  150.  
  151. if ( ! is_numeric( $this->cache[ $group ][ $key ] ) ) 
  152. $this->cache[ $group ][ $key ] = 0; 
  153.  
  154. $offset = (int) $offset; 
  155.  
  156. $this->cache[ $group ][ $key ] -= $offset; 
  157.  
  158. if ( $this->cache[ $group ][ $key ] < 0 ) 
  159. $this->cache[ $group ][ $key ] = 0; 
  160.  
  161. return $this->cache[ $group ][ $key ]; 
  162.  
  163. /** 
  164. * Removes the contents of the cache key in the group. 
  165. * If the cache key does not exist in the group, then nothing will happen. 
  166. * @since 2.0.0 
  167. * @access public 
  168. * @param int|string $key What the contents in the cache are called. 
  169. * @param string $group Optional. Where the cache contents are grouped. Default 'default'. 
  170. * @param bool $deprecated Optional. Unused. Default false. 
  171. * @return bool False if the contents weren't deleted and true on success. 
  172. */ 
  173. public function delete( $key, $group = 'default', $deprecated = false ) { 
  174. if ( empty( $group ) ) 
  175. $group = 'default'; 
  176.  
  177. if ( $this->multisite && ! isset( $this->global_groups[ $group ] ) ) 
  178. $key = $this->blog_prefix . $key; 
  179.  
  180. if ( ! $this->_exists( $key, $group ) ) 
  181. return false; 
  182.  
  183. unset( $this->cache[$group][$key] ); 
  184. return true; 
  185.  
  186. /** 
  187. * Clears the object cache of all data. 
  188. * @since 2.0.0 
  189. * @access public 
  190. * @return true Always returns true. 
  191. */ 
  192. public function flush() { 
  193. $this->cache = array(); 
  194.  
  195. return true; 
  196.  
  197. /** 
  198. * Retrieves the cache contents, if it exists. 
  199. * The contents will be first attempted to be retrieved by searching by the 
  200. * key in the cache group. If the cache is hit (success) then the contents 
  201. * are returned. 
  202. * On failure, the number of cache misses will be incremented. 
  203. * @since 2.0.0 
  204. * @access public 
  205. * @param int|string $key What the contents in the cache are called. 
  206. * @param string $group Optional. Where the cache contents are grouped. Default 'default'. 
  207. * @param string $force Optional. Unused. Whether to force a refetch rather than relying on the local 
  208. * cache. Default false. 
  209. * @param bool $found Optional. Whether the key was found in the cache. Disambiguates a return of 
  210. * false, a storable value. Passed by reference. Default null. 
  211. * @return false|mixed False on failure to retrieve contents or the cache contents on success. 
  212. */ 
  213. public function get( $key, $group = 'default', $force = false, &$found = null ) { 
  214. if ( empty( $group ) ) 
  215. $group = 'default'; 
  216.  
  217. if ( $this->multisite && ! isset( $this->global_groups[ $group ] ) ) 
  218. $key = $this->blog_prefix . $key; 
  219.  
  220. if ( $this->_exists( $key, $group ) ) { 
  221. $found = true; 
  222. $this->cache_hits += 1; 
  223. if ( is_object($this->cache[$group][$key]) ) 
  224. return clone $this->cache[$group][$key]; 
  225. else 
  226. return $this->cache[$group][$key]; 
  227.  
  228. $found = false; 
  229. $this->cache_misses += 1; 
  230. return false; 
  231.  
  232. /** 
  233. * Increments numeric cache item's value. 
  234. * @since 3.3.0 
  235. * @access public 
  236. * @param int|string $key The cache key to increment 
  237. * @param int $offset Optional. The amount by which to increment the item's value. Default 1. 
  238. * @param string $group Optional. The group the key is in. Default 'default'. 
  239. * @return false|int False on failure, the item's new value on success. 
  240. */ 
  241. public function incr( $key, $offset = 1, $group = 'default' ) { 
  242. if ( empty( $group ) ) 
  243. $group = 'default'; 
  244.  
  245. if ( $this->multisite && ! isset( $this->global_groups[ $group ] ) ) 
  246. $key = $this->blog_prefix . $key; 
  247.  
  248. if ( ! $this->_exists( $key, $group ) ) 
  249. return false; 
  250.  
  251. if ( ! is_numeric( $this->cache[ $group ][ $key ] ) ) 
  252. $this->cache[ $group ][ $key ] = 0; 
  253.  
  254. $offset = (int) $offset; 
  255.  
  256. $this->cache[ $group ][ $key ] += $offset; 
  257.  
  258. if ( $this->cache[ $group ][ $key ] < 0 ) 
  259. $this->cache[ $group ][ $key ] = 0; 
  260.  
  261. return $this->cache[ $group ][ $key ]; 
  262.  
  263. /** 
  264. * Replaces the contents in the cache, if contents already exist. 
  265. * @since 2.0.0 
  266. * @access public 
  267. * @see WP_Object_Cache::set() 
  268. * @param int|string $key What to call the contents in the cache. 
  269. * @param mixed $data The contents to store in the cache. 
  270. * @param string $group Optional. Where to group the cache contents. Default 'default'. 
  271. * @param int $expire Optional. When to expire the cache contents. Default 0 (no expiration). 
  272. * @return bool False if not exists, true if contents were replaced. 
  273. */ 
  274. public function replace( $key, $data, $group = 'default', $expire = 0 ) { 
  275. if ( empty( $group ) ) 
  276. $group = 'default'; 
  277.  
  278. $id = $key; 
  279. if ( $this->multisite && ! isset( $this->global_groups[ $group ] ) ) 
  280. $id = $this->blog_prefix . $key; 
  281.  
  282. if ( ! $this->_exists( $id, $group ) ) 
  283. return false; 
  284.  
  285. return $this->set( $key, $data, $group, (int) $expire ); 
  286.  
  287. /** 
  288. * Resets cache keys. 
  289. * @since 3.0.0 
  290. * @access public 
  291. * @deprecated 3.5.0 Use switch_to_blog() 
  292. * @see switch_to_blog() 
  293. */ 
  294. public function reset() { 
  295. _deprecated_function( __FUNCTION__, '3.5.0', 'switch_to_blog()' ); 
  296.  
  297. // Clear out non-global caches since the blog ID has changed. 
  298. foreach ( array_keys( $this->cache ) as $group ) { 
  299. if ( ! isset( $this->global_groups[ $group ] ) ) 
  300. unset( $this->cache[ $group ] ); 
  301.  
  302. /** 
  303. * Sets the data contents into the cache. 
  304. * The cache contents is grouped by the $group parameter followed by the 
  305. * $key. This allows for duplicate ids in unique groups. Therefore, naming of 
  306. * the group should be used with care and should follow normal function 
  307. * naming guidelines outside of core WordPress usage. 
  308. * The $expire parameter is not used, because the cache will automatically 
  309. * expire for each time a page is accessed and PHP finishes. The method is 
  310. * more for cache plugins which use files. 
  311. * @since 2.0.0 
  312. * @access public 
  313. * @param int|string $key What to call the contents in the cache. 
  314. * @param mixed $data The contents to store in the cache. 
  315. * @param string $group Optional. Where to group the cache contents. Default 'default'. 
  316. * @param int $expire Not Used. 
  317. * @return true Always returns true. 
  318. */ 
  319. public function set( $key, $data, $group = 'default', $expire = 0 ) { 
  320. if ( empty( $group ) ) 
  321. $group = 'default'; 
  322.  
  323. if ( $this->multisite && ! isset( $this->global_groups[ $group ] ) ) 
  324. $key = $this->blog_prefix . $key; 
  325.  
  326. if ( is_object( $data ) ) 
  327. $data = clone $data; 
  328.  
  329. $this->cache[$group][$key] = $data; 
  330. return true; 
  331.  
  332. /** 
  333. * Echoes the stats of the caching. 
  334. * Gives the cache hits, and cache misses. Also prints every cached group,  
  335. * key and the data. 
  336. * @since 2.0.0 
  337. * @access public 
  338. */ 
  339. public function stats() { 
  340. echo "<p>"; 
  341. echo "<strong>Cache Hits:</strong> {$this->cache_hits}<br />"; 
  342. echo "<strong>Cache Misses:</strong> {$this->cache_misses}<br />"; 
  343. echo "</p>"; 
  344. echo '<ul>'; 
  345. foreach ($this->cache as $group => $cache) { 
  346. echo "<li><strong>Group:</strong> $group - ( " . number_format( strlen( serialize( $cache ) ) / KB_IN_BYTES, 2 ) . 'k )</li>'; 
  347. echo '</ul>'; 
  348.  
  349. /** 
  350. * Switches the internal blog ID. 
  351. * This changes the blog ID used to create keys in blog specific groups. 
  352. * @since 3.5.0 
  353. * @access public 
  354. * @param int $blog_id Blog ID. 
  355. */ 
  356. public function switch_to_blog( $blog_id ) { 
  357. $blog_id = (int) $blog_id; 
  358. $this->blog_prefix = $this->multisite ? $blog_id . ':' : ''; 
  359.  
  360. /** 
  361. * Serves as a utility function to determine whether a key exists in the cache. 
  362. * @since 3.4.0 
  363. * @access protected 
  364. * @param int|string $key Cache key to check for existence. 
  365. * @param string $group Cache group for the key existence check. 
  366. * @return bool Whether the key exists in the cache for the given group. 
  367. */ 
  368. protected function _exists( $key, $group ) { 
  369. return isset( $this->cache[ $group ] ) && ( isset( $this->cache[ $group ][ $key ] ) || array_key_exists( $key, $this->cache[ $group ] ) ); 
  370.  
  371. /** 
  372. * Sets up object properties; PHP 5 style constructor. 
  373. * @since 2.0.8 
  374. */ 
  375. public function __construct() { 
  376. $this->multisite = is_multisite(); 
  377. $this->blog_prefix = $this->multisite ? get_current_blog_id() . ':' : ''; 
  378.  
  379.  
  380. /** 
  381. * @todo This should be moved to the PHP4 style constructor, PHP5 
  382. * already calls __destruct() 
  383. */ 
  384. register_shutdown_function( array( $this, '__destruct' ) ); 
  385.  
  386. /** 
  387. * Saves the object cache before object is completely destroyed. 
  388. * Called upon object destruction, which should be when PHP ends. 
  389. * @since 2.0.8 
  390. * @return true Always returns true. 
  391. */ 
  392. public function __destruct() { 
  393. return true;