Cache API: Add `wp_cache_flush_group` function.

Add a new plugable function called `wp_cache_flush_group`, that will allow developers to clear whole cache groups with a single call. Developers can detect if their current implementation of an object cache supports flushing by group, by calling `wp_cache_supports_group_flush` which returns true if it is supported. If the developers of the object cache drop-in has not implemented `wp_cache_flush_group` and `wp_cache_supports_group_flush`, these functions are polyfilled and `wp_cache_supports_group_flush` defaults to false.

Props Spacedmonkey, filosofo, ryan, sc0ttkclark, SergeyBiryukov, scribu, Ste_95, dd32, dhilditch, dougal, lucasbustamante, dg12345, tillkruess, peterwilsoncc, flixos90, pbearne.
Fixes #4476.
Built from https://develop.svn.wordpress.org/trunk@53763


git-svn-id: http://core.svn.wordpress.org/trunk@53322 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-includes/cache-compat.php

@@ -141,3 +141,49 @@ if ( ! function_exists( 'wp_cache_flush_runtime' ) ) :
 		return wp_using_ext_object_cache() ? false : wp_cache_flush();
 	}
 endif;
+
+if ( ! function_exists( 'wp_cache_flush_group' ) ) :
+	/**
+	 * Removes all cache items in a group, if the object cache implementation supports it.
+	 * Before calling this method, always check for group flushing support using the
+	 * `wp_cache_supports_group_flush()` method.
+	 *
+	 * @since 6.1.0
+	 *
+	 * @see WP_Object_Cache::flush_group()
+	 * @global WP_Object_Cache $wp_object_cache Object cache global instance.
+	 *
+	 * @param string $group Name of group to remove from cache.
+	 * @return bool True if group was flushed, false otherwise.
+	 */
+	function wp_cache_flush_group( $group ) {
+		global $wp_object_cache;
+
+		if ( ! wp_cache_supports_group_flush() ) {
+			_doing_it_wrong(
+				__FUNCTION__,
+				__( 'Your object cache implementation does not support flushing individual groups.' ),
+				'6.1.0'
+			);
+
+			return false;
+		}
+
+		return $wp_object_cache->flush_group( $group );
+	}
+endif;
+
+if ( ! function_exists( 'wp_cache_supports_group_flush' ) ) :
+	/**
+	 * Whether the object cache implementation supports flushing individual cache groups.
+	 *
+	 * @since 6.1.0
+	 *
+	 * @see WP_Object_Cache::flush_group()
+	 *
+	 * @return bool True if group flushing is supported, false otherwise.
+	 */
+	function wp_cache_supports_group_flush() {
+		return false;
+	}
+endif;

wp-includes/cache.php

@@ -22,6 +22,19 @@ function wp_cache_init() {
 	$GLOBALS['wp_object_cache'] = new WP_Object_Cache();
 }
 
+/**
+ * Whether the object cache implementation supports flushing individual cache groups.
+ *
+ * @since 6.1.0
+ *
+ * @see WP_Object_Cache::flush_group()
+ *
+ * @return bool True if group flushing is supported, false otherwise.
+ */
+function wp_cache_supports_group_flush() {
+	return true;
+}
+
 /**
  * Adds data to the cache, if the cache key doesn't already exist.
  *
@@ -281,6 +294,25 @@ function wp_cache_flush_runtime() {
 	return wp_cache_flush();
 }
 
+/**
+ * Removes all cache items in a group, if the object cache implementation supports it.
+ * Before calling this method, always check for group flushing support using the
+ * `wp_cache_supports_group_flush()` method.
+ *
+ * @since 6.1.0
+ *
+ * @see WP_Object_Cache::flush_group()
+ * @global WP_Object_Cache $wp_object_cache Object cache global instance.
+ *
+ * @param string $group Name of group to remove from cache.
+ * @return bool True if group was flushed, false otherwise.
+ */
+function wp_cache_flush_group( $group ) {
+	global $wp_object_cache;
+
+	return $wp_object_cache->flush_group( $group );
+}
+
 /**
  * Closes the cache.
  *

wp-includes/class-wp-object-cache.php

@@ -290,6 +290,20 @@ class WP_Object_Cache {
 		return $values;
 	}
 
+	/**
+	 * Removes all cache items in a group.
+	 *
+	 * @since 6.1.0
+	 *
+	 * @param string $group Name of group to remove from cache.
+	 * @return true Always returns true.
+	 */
+	public function flush_group( $group ) {
+		unset( $this->cache[ $group ] );
+
+		return true;
+	}
+
 	/**
 	 * Retrieves the cache contents, if it exists.
 	 *

wp-includes/version.php

@@ -16,7 +16,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '6.1-alpha-53762';
+$wp_version = '6.1-alpha-53763';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.