1<?php
2/**
3 * Object Cache API functions missing from 3rd party object caches.
4 *
5 * @link https://developer.wordpress.org/reference/classes/wp_object_cache/
6 *
7 * @package WordPress
8 * @subpackage Cache
9 */
10
11if ( ! function_exists( 'wp_cache_add_multiple' ) ) :
12 /**
13 * Adds multiple values to the cache in one call, if the cache keys don't already exist.
14 *
15 * Compat function to mimic wp_cache_add_multiple().
16 *
17 * @ignore
18 * @since 6.0.0
19 *
20 * @see wp_cache_add_multiple()
21 *
22 * @param array $data Array of keys and values to be added.
23 * @param string $group Optional. Where the cache contents are grouped. Default empty.
24 * @param int $expire Optional. When to expire the cache contents, in seconds.
25 * Default 0 (no expiration).
26 * @return bool[] Array of return values, grouped by key. Each value is either
27 * true on success, or false if cache key and group already exist.
28 */
29 function wp_cache_add_multiple( array $data, $group = '', $expire = 0 ) {
30 $values = array();
31
32 foreach ( $data as $key => $value ) {
33 $values[ $key ] = wp_cache_add( $key, $value, $group, $expire );
34 }
35
36 return $values;
37 }
38endif;
39
40if ( ! function_exists( 'wp_cache_set_multiple' ) ) :
41 /**
42 * Sets multiple values to the cache in one call.
43 *
44 * Differs from wp_cache_add_multiple() in that it will always write data.
45 *
46 * Compat function to mimic wp_cache_set_multiple().
47 *
48 * @ignore
49 * @since 6.0.0
50 *
51 * @see wp_cache_set_multiple()
52 *
53 * @param array $data Array of keys and values to be set.
54 * @param string $group Optional. Where the cache contents are grouped. Default empty.
55 * @param int $expire Optional. When to expire the cache contents, in seconds.
56 * Default 0 (no expiration).
57 * @return bool[] Array of return values, grouped by key. Each value is either
58 * true on success, or false on failure.
59 */
60 function wp_cache_set_multiple( array $data, $group = '', $expire = 0 ) {
61 $values = array();
62
63 foreach ( $data as $key => $value ) {
64 $values[ $key ] = wp_cache_set( $key, $value, $group, $expire );
65 }
66
67 return $values;
68 }
69endif;
70
71if ( ! function_exists( 'wp_cache_get_multiple' ) ) :
72 /**
73 * Retrieves multiple values from the cache in one call.
74 *
75 * Compat function to mimic wp_cache_get_multiple().
76 *
77 * @ignore
78 * @since 5.5.0
79 *
80 * @see wp_cache_get_multiple()
81 *
82 * @param array $keys Array of keys under which the cache contents are stored.
83 * @param string $group Optional. Where the cache contents are grouped. Default empty.
84 * @param bool $force Optional. Whether to force an update of the local cache
85 * from the persistent cache. Default false.
86 * @return array Array of return values, grouped by key. Each value is either
87 * the cache contents on success, or false on failure.
88 */
89 function wp_cache_get_multiple( $keys, $group = '', $force = false ) {
90 $values = array();
91
92 foreach ( $keys as $key ) {
93 $values[ $key ] = wp_cache_get( $key, $group, $force );
94 }
95
96 return $values;
97 }
98endif;
99
100if ( ! function_exists( 'wp_cache_delete_multiple' ) ) :
101 /**
102 * Deletes multiple values from the cache in one call.
103 *
104 * Compat function to mimic wp_cache_delete_multiple().
105 *
106 * @ignore
107 * @since 6.0.0
108 *
109 * @see wp_cache_delete_multiple()
110 *
111 * @param array $keys Array of keys under which the cache to deleted.
112 * @param string $group Optional. Where the cache contents are grouped. Default empty.
113 * @return bool[] Array of return values, grouped by key. Each value is either
114 * true on success, or false if the contents were not deleted.
115 */
116 function wp_cache_delete_multiple( array $keys, $group = '' ) {
117 $values = array();
118
119 foreach ( $keys as $key ) {
120 $values[ $key ] = wp_cache_delete( $key, $group );
121 }
122
123 return $values;
124 }
125endif;
126
127if ( ! function_exists( 'wp_cache_flush_runtime' ) ) :
128 /**
129 * Removes all cache items from the in-memory runtime cache.
130 *
131 * Compat function to mimic wp_cache_flush_runtime().
132 *
133 * @ignore
134 * @since 6.0.0
135 *
136 * @see wp_cache_flush_runtime()
137 *
138 * @return bool True on success, false on failure.
139 */
140 function wp_cache_flush_runtime() {
141 if ( ! wp_cache_supports( 'flush_runtime' ) ) {
142 _doing_it_wrong(
143 __FUNCTION__,
144 __( 'Your object cache implementation does not support flushing the in-memory runtime cache.' ),
145 '6.1.0'
146 );
147
148 return false;
149 }
150
151 return wp_cache_flush();
152 }
153endif;
154
155if ( ! function_exists( 'wp_cache_flush_group' ) ) :
156 /**
157 * Removes all cache items in a group, if the object cache implementation supports it.
158 *
159 * Before calling this function, always check for group flushing support using the
160 * `wp_cache_supports( 'flush_group' )` function.
161 *
162 * @since 6.1.0
163 *
164 * @see WP_Object_Cache::flush_group()
165 * @global WP_Object_Cache $wp_object_cache Object cache global instance.
166 *
167 * @param string $group Name of group to remove from cache.
168 * @return bool True if group was flushed, false otherwise.
169 */
170 function wp_cache_flush_group( $group ) {
171 global $wp_object_cache;
172
173 if ( ! wp_cache_supports( 'flush_group' ) ) {
174 _doing_it_wrong(
175 __FUNCTION__,
176 __( 'Your object cache implementation does not support flushing individual groups.' ),
177 '6.1.0'
178 );
179
180 return false;
181 }
182
183 return $wp_object_cache->flush_group( $group );
184 }
185endif;
186
187if ( ! function_exists( 'wp_cache_supports' ) ) :
188 /**
189 * Determines whether the object cache implementation supports a particular feature.
190 *
191 * @since 6.1.0
192 *
193 * @param string $feature Name of the feature to check for. Possible values include:
194 * 'add_multiple', 'set_multiple', 'get_multiple', 'delete_multiple',
195 * 'flush_runtime', 'flush_group'.
196 * @return bool True if the feature is supported, false otherwise.
197 */
198 function wp_cache_supports( $feature ) {
199 return false;
200 }
201endif;
202
203if ( ! function_exists( 'wp_cache_get_salted' ) ) :
204 /**
205 * Retrieves cached data if valid and unchanged.
206 *
207 * @since 6.9.0
208 *
209 * @param string $cache_key The cache key used for storage and retrieval.
210 * @param string $group The cache group used for organizing data.
211 * @param string|string[] $salt The timestamp (or multiple timestamps if an array) indicating when the cache group(s) were last updated.
212 * @return mixed|false The cached data if valid, or false if the cache does not exist or is outdated.
213 */
214 function wp_cache_get_salted( $cache_key, $group, $salt ) {
215 $salt = is_array( $salt ) ? implode( ':', $salt ) : $salt;
216 $cache = wp_cache_get( $cache_key, $group );
217
218 if ( ! is_array( $cache ) ) {
219 return false;
220 }
221
222 if ( ! isset( $cache['salt'] ) || ! isset( $cache['data'] ) || $salt !== $cache['salt'] ) {
223 return false;
224 }
225
226 return $cache['data'];
227 }
228endif;
229
230if ( ! function_exists( 'wp_cache_set_salted' ) ) :
231 /**
232 * Stores salted data in the cache.
233 *
234 * @since 6.9.0
235 *
236 * @param string $cache_key The cache key under which to store the data.
237 * @param mixed $data The data to be cached.
238 * @param string $group The cache group to which the data belongs.
239 * @param string|string[] $salt The timestamp (or multiple timestamps if an array) indicating when the cache group(s) were last updated.
240 * @param int $expire Optional. When to expire the cache contents, in seconds.
241 * Default 0 (no expiration).
242 * @return bool True on success, false on failure.
243 */
244 function wp_cache_set_salted( $cache_key, $data, $group, $salt, $expire = 0 ) {
245 $salt = is_array( $salt ) ? implode( ':', $salt ) : $salt;
246 return wp_cache_set(
247 $cache_key,
248 array(
249 'data' => $data,
250 'salt' => $salt,
251 ),
252 $group,
253 $expire
254 );
255 }
256endif;
257
258if ( ! function_exists( 'wp_cache_get_multiple_salted' ) ) :
259 /**
260 * Retrieves multiple items from the cache, only considering valid and unchanged items.
261 *
262 * @since 6.9.0
263 *
264 * @param array $cache_keys Array of cache keys to retrieve.
265 * @param string $group The group of the cache to check.
266 * @param string|string[] $salt The timestamp (or multiple timestamps if an array) indicating when the cache group(s) were last updated.
267 * @return array An associative array containing cache values. Values are `false` if they are not found or outdated.
268 */
269 function wp_cache_get_multiple_salted( $cache_keys, $group, $salt ) {
270 $salt = is_array( $salt ) ? implode( ':', $salt ) : $salt;
271 $cache = wp_cache_get_multiple( $cache_keys, $group );
272
273 foreach ( $cache as $key => $value ) {
274 if ( ! is_array( $value ) ) {
275 $cache[ $key ] = false;
276 continue;
277 }
278 if ( ! isset( $value['salt'], $value['data'] ) || $salt !== $value['salt'] ) {
279 $cache[ $key ] = false;
280 continue;
281 }
282 $cache[ $key ] = $value['data'];
283 }
284
285 return $cache;
286 }
287endif;
288
289if ( ! function_exists( 'wp_cache_set_multiple_salted' ) ) :
290 /**
291 * Stores multiple pieces of salted data in the cache.
292 *
293 * @since 6.9.0
294 *
295 * @param mixed $data Data to be stored in the cache for all keys.
296 * @param string $group Group to which the cached data belongs.
297 * @param string|string[] $salt The timestamp (or multiple timestamps if an array) indicating when the cache group(s) were last updated.
298 * @param int $expire Optional. When to expire the cache contents, in seconds.
299 * Default 0 (no expiration).
300 * @return bool[] Array of return values, grouped by key. Each value is either
301 * true on success, or false on failure.
302 */
303 function wp_cache_set_multiple_salted( $data, $group, $salt, $expire = 0 ) {
304 $salt = is_array( $salt ) ? implode( ':', $salt ) : $salt;
305 $new_cache = array();
306 foreach ( $data as $key => $value ) {
307 $new_cache[ $key ] = array(
308 'data' => $value,
309 'salt' => $salt,
310 );
311 }
312 return wp_cache_set_multiple( $new_cache, $group, $expire );
313 }
314endif;
315