cache.php 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415
  1. <?php
  2. /**
  3. * Object Cache API
  4. *
  5. * @link https://developer.wordpress.org/reference/classes/wp_object_cache/
  6. *
  7. * @package WordPress
  8. * @subpackage Cache
  9. */
  10. /** WP_Object_Cache class */
  11. require_once ABSPATH . WPINC . '/class-wp-object-cache.php';
  12. /**
  13. * Sets up Object Cache Global and assigns it.
  14. *
  15. * @since 2.0.0
  16. *
  17. * @global WP_Object_Cache $wp_object_cache
  18. */
  19. function wp_cache_init() {
  20. $GLOBALS['wp_object_cache'] = new WP_Object_Cache();
  21. }
  22. /**
  23. * Adds data to the cache, if the cache key doesn't already exist.
  24. *
  25. * @since 2.0.0
  26. *
  27. * @see WP_Object_Cache::add()
  28. * @global WP_Object_Cache $wp_object_cache Object cache global instance.
  29. *
  30. * @param int|string $key The cache key to use for retrieval later.
  31. * @param mixed $data The data to add to the cache.
  32. * @param string $group Optional. The group to add the cache to. Enables the same key
  33. * to be used across groups. Default empty.
  34. * @param int $expire Optional. When the cache data should expire, in seconds.
  35. * Default 0 (no expiration).
  36. * @return bool True on success, false if cache key and group already exist.
  37. */
  38. function wp_cache_add( $key, $data, $group = '', $expire = 0 ) {
  39. global $wp_object_cache;
  40. return $wp_object_cache->add( $key, $data, $group, (int) $expire );
  41. }
  42. /**
  43. * Adds multiple values to the cache in one call.
  44. *
  45. * @since 6.0.0
  46. *
  47. * @see WP_Object_Cache::add_multiple()
  48. * @global WP_Object_Cache $wp_object_cache Object cache global instance.
  49. *
  50. * @param array $data Array of keys and values to be set.
  51. * @param string $group Optional. Where the cache contents are grouped. Default empty.
  52. * @param int $expire Optional. When to expire the cache contents, in seconds.
  53. * Default 0 (no expiration).
  54. * @return bool[] Array of return values, grouped by key. Each value is either
  55. * true on success, or false if cache key and group already exist.
  56. */
  57. function wp_cache_add_multiple( array $data, $group = '', $expire = 0 ) {
  58. global $wp_object_cache;
  59. return $wp_object_cache->add_multiple( $data, $group, $expire );
  60. }
  61. /**
  62. * Replaces the contents of the cache with new data.
  63. *
  64. * @since 2.0.0
  65. *
  66. * @see WP_Object_Cache::replace()
  67. * @global WP_Object_Cache $wp_object_cache Object cache global instance.
  68. *
  69. * @param int|string $key The key for the cache data that should be replaced.
  70. * @param mixed $data The new data to store in the cache.
  71. * @param string $group Optional. The group for the cache data that should be replaced.
  72. * Default empty.
  73. * @param int $expire Optional. When to expire the cache contents, in seconds.
  74. * Default 0 (no expiration).
  75. * @return bool True if contents were replaced, false if original value does not exist.
  76. */
  77. function wp_cache_replace( $key, $data, $group = '', $expire = 0 ) {
  78. global $wp_object_cache;
  79. return $wp_object_cache->replace( $key, $data, $group, (int) $expire );
  80. }
  81. /**
  82. * Saves the data to the cache.
  83. *
  84. * Differs from wp_cache_add() and wp_cache_replace() in that it will always write data.
  85. *
  86. * @since 2.0.0
  87. *
  88. * @see WP_Object_Cache::set()
  89. * @global WP_Object_Cache $wp_object_cache Object cache global instance.
  90. *
  91. * @param int|string $key The cache key to use for retrieval later.
  92. * @param mixed $data The contents to store in the cache.
  93. * @param string $group Optional. Where to group the cache contents. Enables the same key
  94. * to be used across groups. Default empty.
  95. * @param int $expire Optional. When to expire the cache contents, in seconds.
  96. * Default 0 (no expiration).
  97. * @return bool True on success, false on failure.
  98. */
  99. function wp_cache_set( $key, $data, $group = '', $expire = 0 ) {
  100. global $wp_object_cache;
  101. return $wp_object_cache->set( $key, $data, $group, (int) $expire );
  102. }
  103. /**
  104. * Sets multiple values to the cache in one call.
  105. *
  106. * @since 6.0.0
  107. *
  108. * @see WP_Object_Cache::set_multiple()
  109. * @global WP_Object_Cache $wp_object_cache Object cache global instance.
  110. *
  111. * @param array $data Array of keys and values to be set.
  112. * @param string $group Optional. Where the cache contents are grouped. Default empty.
  113. * @param int $expire Optional. When to expire the cache contents, in seconds.
  114. * Default 0 (no expiration).
  115. * @return bool[] Array of return values, grouped by key. Each value is either
  116. * true on success, or false on failure.
  117. */
  118. function wp_cache_set_multiple( array $data, $group = '', $expire = 0 ) {
  119. global $wp_object_cache;
  120. return $wp_object_cache->set_multiple( $data, $group, $expire );
  121. }
  122. /**
  123. * Retrieves the cache contents from the cache by key and group.
  124. *
  125. * @since 2.0.0
  126. *
  127. * @see WP_Object_Cache::get()
  128. * @global WP_Object_Cache $wp_object_cache Object cache global instance.
  129. *
  130. * @param int|string $key The key under which the cache contents are stored.
  131. * @param string $group Optional. Where the cache contents are grouped. Default empty.
  132. * @param bool $force Optional. Whether to force an update of the local cache
  133. * from the persistent cache. Default false.
  134. * @param bool $found Optional. Whether the key was found in the cache (passed by reference).
  135. * Disambiguates a return of false, a storable value. Default null.
  136. * @return mixed|false The cache contents on success, false on failure to retrieve contents.
  137. */
  138. function wp_cache_get( $key, $group = '', $force = false, &$found = null ) {
  139. global $wp_object_cache;
  140. return $wp_object_cache->get( $key, $group, $force, $found );
  141. }
  142. /**
  143. * Retrieves multiple values from the cache in one call.
  144. *
  145. * @since 5.5.0
  146. *
  147. * @see WP_Object_Cache::get_multiple()
  148. * @global WP_Object_Cache $wp_object_cache Object cache global instance.
  149. *
  150. * @param array $keys Array of keys under which the cache contents are stored.
  151. * @param string $group Optional. Where the cache contents are grouped. Default empty.
  152. * @param bool $force Optional. Whether to force an update of the local cache
  153. * from the persistent cache. Default false.
  154. * @return array Array of return values, grouped by key. Each value is either
  155. * the cache contents on success, or false on failure.
  156. */
  157. function wp_cache_get_multiple( $keys, $group = '', $force = false ) {
  158. global $wp_object_cache;
  159. return $wp_object_cache->get_multiple( $keys, $group, $force );
  160. }
  161. /**
  162. * Removes the cache contents matching key and group.
  163. *
  164. * @since 2.0.0
  165. *
  166. * @see WP_Object_Cache::delete()
  167. * @global WP_Object_Cache $wp_object_cache Object cache global instance.
  168. *
  169. * @param int|string $key What the contents in the cache are called.
  170. * @param string $group Optional. Where the cache contents are grouped. Default empty.
  171. * @return bool True on successful removal, false on failure.
  172. */
  173. function wp_cache_delete( $key, $group = '' ) {
  174. global $wp_object_cache;
  175. return $wp_object_cache->delete( $key, $group );
  176. }
  177. /**
  178. * Deletes multiple values from the cache in one call.
  179. *
  180. * @since 6.0.0
  181. *
  182. * @see WP_Object_Cache::delete_multiple()
  183. * @global WP_Object_Cache $wp_object_cache Object cache global instance.
  184. *
  185. * @param array $keys Array of keys under which the cache to deleted.
  186. * @param string $group Optional. Where the cache contents are grouped. Default empty.
  187. * @return bool[] Array of return values, grouped by key. Each value is either
  188. * true on success, or false if the contents were not deleted.
  189. */
  190. function wp_cache_delete_multiple( array $keys, $group = '' ) {
  191. global $wp_object_cache;
  192. return $wp_object_cache->delete_multiple( $keys, $group );
  193. }
  194. /**
  195. * Increments numeric cache item's value.
  196. *
  197. * @since 3.3.0
  198. *
  199. * @see WP_Object_Cache::incr()
  200. * @global WP_Object_Cache $wp_object_cache Object cache global instance.
  201. *
  202. * @param int|string $key The key for the cache contents that should be incremented.
  203. * @param int $offset Optional. The amount by which to increment the item's value.
  204. * Default 1.
  205. * @param string $group Optional. The group the key is in. Default empty.
  206. * @return int|false The item's new value on success, false on failure.
  207. */
  208. function wp_cache_incr( $key, $offset = 1, $group = '' ) {
  209. global $wp_object_cache;
  210. return $wp_object_cache->incr( $key, $offset, $group );
  211. }
  212. /**
  213. * Decrements numeric cache item's value.
  214. *
  215. * @since 3.3.0
  216. *
  217. * @see WP_Object_Cache::decr()
  218. * @global WP_Object_Cache $wp_object_cache Object cache global instance.
  219. *
  220. * @param int|string $key The cache key to decrement.
  221. * @param int $offset Optional. The amount by which to decrement the item's value.
  222. * Default 1.
  223. * @param string $group Optional. The group the key is in. Default empty.
  224. * @return int|false The item's new value on success, false on failure.
  225. */
  226. function wp_cache_decr( $key, $offset = 1, $group = '' ) {
  227. global $wp_object_cache;
  228. return $wp_object_cache->decr( $key, $offset, $group );
  229. }
  230. /**
  231. * Removes all cache items.
  232. *
  233. * @since 2.0.0
  234. *
  235. * @see WP_Object_Cache::flush()
  236. * @global WP_Object_Cache $wp_object_cache Object cache global instance.
  237. *
  238. * @return bool True on success, false on failure.
  239. */
  240. function wp_cache_flush() {
  241. global $wp_object_cache;
  242. return $wp_object_cache->flush();
  243. }
  244. /**
  245. * Removes all cache items from the in-memory runtime cache.
  246. *
  247. * @since 6.0.0
  248. *
  249. * @see WP_Object_Cache::flush()
  250. *
  251. * @return bool True on success, false on failure.
  252. */
  253. function wp_cache_flush_runtime() {
  254. return wp_cache_flush();
  255. }
  256. /**
  257. * Removes all cache items in a group, if the object cache implementation supports it.
  258. *
  259. * Before calling this function, always check for group flushing support using the
  260. * `wp_cache_supports( 'flush_group' )` function.
  261. *
  262. * @since 6.1.0
  263. *
  264. * @see WP_Object_Cache::flush_group()
  265. * @global WP_Object_Cache $wp_object_cache Object cache global instance.
  266. *
  267. * @param string $group Name of group to remove from cache.
  268. * @return bool True if group was flushed, false otherwise.
  269. */
  270. function wp_cache_flush_group( $group ) {
  271. global $wp_object_cache;
  272. return $wp_object_cache->flush_group( $group );
  273. }
  274. /**
  275. * Determines whether the object cache implementation supports a particular feature.
  276. *
  277. * @since 6.1.0
  278. *
  279. * @param string $feature Name of the feature to check for. Possible values include:
  280. * 'add_multiple', 'set_multiple', 'get_multiple', 'delete_multiple',
  281. * 'flush_runtime', 'flush_group'.
  282. * @return bool True if the feature is supported, false otherwise.
  283. */
  284. function wp_cache_supports( $feature ) {
  285. switch ( $feature ) {
  286. case 'add_multiple':
  287. case 'set_multiple':
  288. case 'get_multiple':
  289. case 'delete_multiple':
  290. case 'flush_runtime':
  291. case 'flush_group':
  292. return true;
  293. default:
  294. return false;
  295. }
  296. }
  297. /**
  298. * Closes the cache.
  299. *
  300. * This function has ceased to do anything since WordPress 2.5. The
  301. * functionality was removed along with the rest of the persistent cache.
  302. *
  303. * This does not mean that plugins can't implement this function when they need
  304. * to make sure that the cache is cleaned up after WordPress no longer needs it.
  305. *
  306. * @since 2.0.0
  307. *
  308. * @return true Always returns true.
  309. */
  310. function wp_cache_close() {
  311. return true;
  312. }
  313. /**
  314. * Adds a group or set of groups to the list of global groups.
  315. *
  316. * @since 2.6.0
  317. *
  318. * @see WP_Object_Cache::add_global_groups()
  319. * @global WP_Object_Cache $wp_object_cache Object cache global instance.
  320. *
  321. * @param string|string[] $groups A group or an array of groups to add.
  322. */
  323. function wp_cache_add_global_groups( $groups ) {
  324. global $wp_object_cache;
  325. $wp_object_cache->add_global_groups( $groups );
  326. }
  327. /**
  328. * Adds a group or set of groups to the list of non-persistent groups.
  329. *
  330. * @since 2.6.0
  331. *
  332. * @param string|string[] $groups A group or an array of groups to add.
  333. */
  334. function wp_cache_add_non_persistent_groups( $groups ) {
  335. // Default cache doesn't persist so nothing to do here.
  336. }
  337. /**
  338. * Switches the internal blog ID.
  339. *
  340. * This changes the blog id used to create keys in blog specific groups.
  341. *
  342. * @since 3.5.0
  343. *
  344. * @see WP_Object_Cache::switch_to_blog()
  345. * @global WP_Object_Cache $wp_object_cache Object cache global instance.
  346. *
  347. * @param int $blog_id Site ID.
  348. */
  349. function wp_cache_switch_to_blog( $blog_id ) {
  350. global $wp_object_cache;
  351. $wp_object_cache->switch_to_blog( $blog_id );
  352. }
  353. /**
  354. * Resets internal cache keys and structures.
  355. *
  356. * If the cache back end uses global blog or site IDs as part of its cache keys,
  357. * this function instructs the back end to reset those keys and perform any cleanup
  358. * since blog or site IDs have changed since cache init.
  359. *
  360. * This function is deprecated. Use wp_cache_switch_to_blog() instead of this
  361. * function when preparing the cache for a blog switch. For clearing the cache
  362. * during unit tests, consider using wp_cache_init(). wp_cache_init() is not
  363. * recommended outside of unit tests as the performance penalty for using it is high.
  364. *
  365. * @since 3.0.0
  366. * @deprecated 3.5.0 Use wp_cache_switch_to_blog()
  367. * @see WP_Object_Cache::reset()
  368. *
  369. * @global WP_Object_Cache $wp_object_cache Object cache global instance.
  370. */
  371. function wp_cache_reset() {
  372. _deprecated_function( __FUNCTION__, '3.5.0', 'wp_cache_switch_to_blog()' );
  373. global $wp_object_cache;
  374. $wp_object_cache->reset();
  375. }