Cache API: Make the placement of wp_cache_flush_group() more consistent.

Includes:
* Placing `WP_Object_Cache::flush_group()` next to `::flush()`.
* Placing `wp_cache_supports_group_flush()` next to `wp_cache_flush_group()`.
* Placing the `wp_cache_flush_group()` unit test next to the `::flush()` method test.
* Removing test name from assertion messages, as it is already mentioned directly above in case of failure.
* Adjusting function descriptions per the documentation standards.

Follow-up to [52706], [53763].

See #55647, WordPress#4476.

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

Author: SergeyBiryukov

src/wp-includes/cache-compat.php

@@ -145,8 +145,9 @@ function wp_cache_flush_runtime() {
 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.
+	 *
+	 * Before calling this function, always check for group flushing support using the
+	 * `wp_cache_supports_group_flush()` function.
 	 *
 	 * @since 6.1.0
 	 *
@@ -175,7 +176,7 @@ function wp_cache_flush_group( $group ) {
 
 if ( ! function_exists( 'wp_cache_supports_group_flush' ) ) :
 	/**
-	 * Whether the object cache implementation supports flushing individual cache groups.
+	 * Determines whether the object cache implementation supports flushing individual cache groups.
 	 *
 	 * @since 6.1.0
 	 *

src/wp-includes/cache.php

@@ -22,19 +22,6 @@ 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.
  *
@@ -296,8 +283,9 @@ function wp_cache_flush_runtime() {
 
 /**
  * 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.
+ *
+ * Before calling this function, always check for group flushing support using the
+ * `wp_cache_supports_group_flush()` function.
  *
  * @since 6.1.0
  *
@@ -313,6 +301,19 @@ function wp_cache_flush_group( $group ) {
 	return $wp_object_cache->flush_group( $group );
 }
 
+/**
+ * Determines 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;
+}
+
 /**
  * Closes the cache.
  *

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

@@ -290,20 +290,6 @@ public function set_multiple( array $data, $group = '', $expire = 0 ) {
 		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.
 	 *
@@ -509,6 +495,20 @@ public function flush() {
 		return true;
 	}
 
+	/**
+	 * 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;
+	}
+
 	/**
 	 * Sets the list of global cache groups.
 	 *

tests/phpunit/includes/object-cache.php

@@ -284,6 +284,17 @@ function wp_cache_flush( $delay = 0 ) {
 	return $wp_object_cache->flush( $delay );
 }
 
+/**
+ * Whether the object cache implementation supports flushing individual cache groups.
+ *
+ * @since 6.1.0
+ *
+ * @return bool True if group flushing is supported, false otherwise.
+ */
+function wp_cache_supports_group_flush() {
+	return false;
+}
+
 /**
  * Retrieves object from cache.
  *
@@ -745,17 +756,6 @@ function wp_cache_init() {
 	$wp_object_cache = new WP_Object_Cache();
 }
 
-/**
- * Whether the object cache implementation supports flushing individual cache groups.
- *
- * @since 6.1.0
- *
- * @return bool True if group flushing is supported, false otherwise.
- */
-function wp_cache_supports_group_flush() {
-	return false;
-}
-
 /**
  * Adds a group or set of groups to the list of non-persistent groups.
  *

tests/phpunit/tests/cache.php

@@ -129,6 +129,36 @@ public function test_flush() {
 		$this->assertFalse( $this->cache->get( $key ) );
 	}
 
+	/**
+	 * @ticket 4476
+	 * @ticket 9773
+	 *
+	 * @covers ::wp_cache_flush_group
+	 */
+	public function test_wp_cache_flush_group() {
+		$key = 'my-key';
+		$val = 'my-val';
+
+		wp_cache_set( $key, $val, 'group-test' );
+		wp_cache_set( $key, $val, 'group-kept' );
+
+		$this->assertSame( $val, wp_cache_get( $key, 'group-test' ), 'group-test should contain my-val' );
+
+		if ( wp_using_ext_object_cache() ) {
+			$this->setExpectedIncorrectUsage( 'wp_cache_flush_group' );
+		}
+
+		$results = wp_cache_flush_group( 'group-test' );
+
+		if ( wp_using_ext_object_cache() ) {
+			$this->assertFalse( $results );
+		} else {
+			$this->assertTrue( $results );
+			$this->assertFalse( wp_cache_get( $key, 'group-test' ), 'group-test should return false' );
+			$this->assertSame( $val, wp_cache_get( $key, 'group-kept' ), 'group-kept should still contain my-val' );
+		}
+	}
+
 	// Make sure objects are cloned going to and from the cache.
 	public function test_object_refs() {
 		$key           = __FUNCTION__ . '_1';
@@ -415,36 +445,4 @@ public function test_wp_cache_delete_multiple() {
 
 		$this->assertSame( $expected, $found );
 	}
-
-	/**
-	 * @ticket 4476
-	 * @ticket 9773
-	 *
-	 * test wp_cache_flush_group
-	 *
-	 * @covers ::wp_cache_flush_group
-	 */
-	public function test_wp_cache_flush_group() {
-		$key = 'my-key';
-		$val = 'my-val';
-
-		wp_cache_set( $key, $val, 'group-test' );
-		wp_cache_set( $key, $val, 'group-kept' );
-
-		$this->assertSame( $val, wp_cache_get( $key, 'group-test' ), 'test_wp_cache_flush_group: group-test should contain my-val' );
-
-		if ( wp_using_ext_object_cache() ) {
-			$this->setExpectedIncorrectUsage( 'wp_cache_flush_group' );
-		}
-
-		$results = wp_cache_flush_group( 'group-test' );
-
-		if ( wp_using_ext_object_cache() ) {
-			$this->assertFalse( $results );
-		} else {
-			$this->assertTrue( $results );
-			$this->assertFalse( wp_cache_get( $key, 'group-test' ), 'test_wp_cache_flush_group: group-test should return false' );
-			$this->assertSame( $val, wp_cache_get( $key, 'group-kept' ), 'test_wp_cache_flush_group: group-kept should still contain my-val' );
-		}
-	}
 }

tests/phpunit/tests/pluggable.php

@@ -268,7 +268,6 @@ public function get_pluggable_function_signatures() {
 
 					// wp-includes/cache.php:
 					'wp_cache_init'                      => array(),
-					'wp_cache_supports_group_flush'      => array(),
 					'wp_cache_add'                       => array(
 						'key',
 						'data',
@@ -329,6 +328,7 @@ public function get_pluggable_function_signatures() {
 					'wp_cache_flush'                     => array(),
 					'wp_cache_flush_runtime'             => array(),
 					'wp_cache_flush_group'               => array( 'group' ),
+					'wp_cache_supports_group_flush'      => array(),
 					'wp_cache_close'                     => array(),
 					'wp_cache_add_global_groups'         => array( 'groups' ),
 					'wp_cache_add_non_persistent_groups' => array( 'groups' ),