Cache API: Introduce wp_cache_supports() function.

WordPress has recently introduced a variety of caching API improvements:

* `wp_cache_add_multiple()`
* `wp_cache_set_multiple()`
* `wp_cache_get_multiple()`
* `wp_cache_delete_multiple()`
* `wp_cache_flush_runtime()`
* `wp_cache_flush_group()`

Although WordPress core provides a compatibility layer if these functions are missing from third-party object cache implementations, there should be a method of checking whether the cache backend supports a particular feature.

This commit aims to improve developer experience by allowing third-party object cache plugins to declare a `wp_cache_supports()` function and correctly list their supported features:

* `add_multiple`
* `set_multiple`
* `get_multiple`
* `delete_multiple`
* `flush_runtime`
* `flush_group`

Note: The `wp_cache_supports()` function replaces and supersedes the `wp_cache_supports_group_flush()` function added earlier.

Follow-up to [47938], [47944], [52700], [52703], [52706], [52708], [53763], [53767], [54423].

Props johnjamesjacoby, tillkruess, spacedmonkey, SergeyBiryukov.
Fixes #56605.

git-svn-id: https://develop.svn.wordpress.org/trunk@54448 602fd350-edb4-49c9-b593-d223f7449a82

src/wp-includes/cache-compat.php

@@ -138,7 +138,17 @@ if ( ! function_exists( 'wp_cache_flush_runtime' ) ) :
 	 * @return bool True on success, false on failure.
 	 */
 	function wp_cache_flush_runtime() {
-		return wp_using_ext_object_cache() ? false : wp_cache_flush();
+		if ( ! wp_cache_supports( 'flush_runtime' ) ) {
+			_doing_it_wrong(
+				__FUNCTION__,
+				__( 'Your object cache implementation does not support flushing the in-memory runtime cache.' ),
+				'6.1.0'
+			);
+
+			return false;
+		}
+
+		return wp_cache_flush();
 	}
 endif;
 
@@ -147,7 +157,7 @@ if ( ! function_exists( 'wp_cache_flush_group' ) ) :
 	 * Removes all cache items in a group, if the object cache implementation supports it.
 	 *
 	 * Before calling this function, always check for group flushing support using the
-	 * `wp_cache_supports_group_flush()` function.
+	 * `wp_cache_supports( 'flush_group' )` function.
 	 *
 	 * @since 6.1.0
 	 *
@@ -160,7 +170,7 @@ if ( ! function_exists( 'wp_cache_flush_group' ) ) :
 	function wp_cache_flush_group( $group ) {
 		global $wp_object_cache;
 
-		if ( ! wp_cache_supports_group_flush() ) {
+		if ( ! wp_cache_supports( 'flush_group' ) ) {
 			_doing_it_wrong(
 				__FUNCTION__,
 				__( 'Your object cache implementation does not support flushing individual groups.' ),
@@ -174,17 +184,18 @@ if ( ! function_exists( 'wp_cache_flush_group' ) ) :
 	}
 endif;
 
-if ( ! function_exists( 'wp_cache_supports_group_flush' ) ) :
+if ( ! function_exists( 'wp_cache_supports' ) ) :
 	/**
-	 * Determines whether the object cache implementation supports flushing individual cache groups.
+	 * Determines whether the object cache implementation supports a particular feature.
 	 *
 	 * @since 6.1.0
 	 *
-	 * @see WP_Object_Cache::flush_group()
-	 *
-	 * @return bool True if group flushing is supported, false otherwise.
+	 * @param string $feature Name of the feature to check for. Possible values include:
+	 *                        'add_multiple', 'set_multiple', 'get_multiple', 'delete_multiple',
+	 *                        'flush_runtime', 'flush_group'.
+	 * @return bool True if the feature is supported, false otherwise.
 	 */
-	function wp_cache_supports_group_flush() {
+	function wp_cache_supports( $feature ) {
 		return false;
 	}
 endif;

src/wp-includes/cache.php

@@ -285,7 +285,7 @@ function wp_cache_flush_runtime() {
  * Removes all cache items in a group, if the object cache implementation supports it.
  *
  * Before calling this function, always check for group flushing support using the
- * `wp_cache_supports_group_flush()` function.
+ * `wp_cache_supports( 'flush_group' )` function.
  *
  * @since 6.1.0
  *
@@ -302,16 +302,28 @@ function wp_cache_flush_group( $group ) {
 }
 
 /**
- * Determines whether the object cache implementation supports flushing individual cache groups.
+ * Determines whether the object cache implementation supports a particular feature.
  *
  * @since 6.1.0
  *
- * @see WP_Object_Cache::flush_group()
- *
- * @return bool True if group flushing is supported, false otherwise.
+ * @param string $feature Name of the feature to check for. Possible values include:
+ *                        'add_multiple', 'set_multiple', 'get_multiple', 'delete_multiple',
+ *                        'flush_runtime', 'flush_group'.
+ * @return bool True if the feature is supported, false otherwise.
  */
-function wp_cache_supports_group_flush() {
-	return true;
+function wp_cache_supports( $feature ) {
+	switch ( $feature ) {
+		case 'add_multiple':
+		case 'set_multiple':
+		case 'get_multiple':
+		case 'delete_multiple':
+		case 'flush_runtime':
+		case 'flush_group':
+			return true;
+
+		default:
+			return false;
+	}
 }
 
 /**

tests/phpunit/includes/object-cache.php

@@ -313,13 +313,16 @@ function wp_cache_flush( $delay = 0 ) {
 }
 
 /**
- * Whether the object cache implementation supports flushing individual cache groups.
+ * Determines whether the object cache implementation supports a particular feature.
  *
  * @since 6.1.0
  *
- * @return bool True if group flushing is supported, false otherwise.
+ * @param string $feature Name of the feature to check for. Possible values include:
+ *                        'add_multiple', 'set_multiple', 'get_multiple', 'delete_multiple',
+ *                        'flush_runtime', 'flush_group'.
+ * @return bool True if the feature is supported, false otherwise.
  */
-function wp_cache_supports_group_flush() {
+function wp_cache_supports( $feature ) {
 	return false;
 }
 

tests/phpunit/tests/pluggable.php

@@ -326,7 +326,7 @@ class Tests_Pluggable extends WP_UnitTestCase {
 					'wp_cache_flush'                     => array(),
 					'wp_cache_flush_runtime'             => array(),
 					'wp_cache_flush_group'               => array( 'group' ),
-					'wp_cache_supports_group_flush'      => array(),
+					'wp_cache_supports'                  => array( 'feature' ),
 					'wp_cache_close'                     => array(),
 					'wp_cache_add_global_groups'         => array( 'groups' ),
 					'wp_cache_add_non_persistent_groups' => array( 'groups' ),