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