Multisite: Establish `clean_blog_cache()` as a replacement for `refresh_blog_details()`.

Going forward, `clean_blog_cache()` is recommended to be used instead of `refresh_blog_details()`. It has been adjusted to match the functionality of the latter, with the exception that it always requires a site ID or object to be passed. The `refresh_blog_details` action has been deprecated in favor of the `clean_site_cache` action. The function itself is not formally deprecated at this point, but will likely be in the near future.

Props spacedmonkey.
Fixes #40201.


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

src/wp-includes/ms-blogs.php

@@ -265,28 +265,7 @@ function refresh_blog_details( $blog_id = 0 ) {
 		$blog_id = get_current_blog_id();
 	}
 
-	$details = get_site( $blog_id );
+	clean_blog_cache( $blog_id );
-	if ( ! $details ) {
-		// Make sure clean_blog_cache() gets the blog ID
-		// when the blog has been previously cached as
-		// non-existent.
-		$details = (object) array(
-			'blog_id' => $blog_id,
-			'domain' => null,
-			'path' => null
-		);
-	}
-
-	clean_blog_cache( $details );
-
-	/**
-	 * Fires after the blog details cache is cleared.
-	 *
-	 * @since 3.4.0
-	 *
-	 * @param int $blog_id Blog ID.
-	 */
-	do_action( 'refresh_blog_details', $blog_id );
 }
 
 /**
@@ -443,7 +422,7 @@ function update_blog_details( $blog_id, $details = array() ) {
  *
  * @global bool $_wp_suspend_cache_invalidation
  *
- * @param WP_Site $blog The site object to be cleared from cache.
+ * @param WP_Site|int $blog The site object or ID to be cleared from cache.
  */
 function clean_blog_cache( $blog ) {
 	global $_wp_suspend_cache_invalidation;
@@ -452,6 +431,25 @@ function clean_blog_cache( $blog ) {
 		return;
 	}
 
+	if ( empty( $blog ) ) {
+		return;
+	}
+
+	$blog_id = $blog;
+	$blog = get_site( $blog_id );
+	if ( ! $blog ) {
+		if ( ! is_numeric( $blog_id ) ) {
+			return;
+		}
+
+		// Make sure a WP_Site object exists even when the site has been deleted.
+		$blog = new WP_Site( (object) array(
+			'blog_id' => $blog_id,
+			'domain'  => null,
+			'path'    => null,
+		) );
+	}
+
 	$blog_id = $blog->blog_id;
 	$domain_path_key = md5( $blog->domain . $blog->path );
 
@@ -476,6 +474,16 @@ function clean_blog_cache( $blog ) {
 	do_action( 'clean_site_cache', $blog_id, $blog, $domain_path_key );
 
 	wp_cache_set( 'last_changed', microtime(), 'sites' );
+
+	/**
+	 * Fires after the blog details cache is cleared.
+	 *
+	 * @since 3.4.0
+	 * @deprecated 4.9.0 Use clean_site_cache
+	 *
+	 * @param int $blog_id Blog ID.
+	 */
+	do_action_deprecated( 'refresh_blog_details', array( $blog_id ), '4.9.0', 'clean_site_cache' );
 }
 
 /**

tests/phpunit/tests/multisite/site.php

@@ -1084,6 +1084,32 @@ class Tests_Multisite_Site extends WP_UnitTestCase {
 		$this->assertFalse( wp_cache_get( $key, $group ) );
 	}
 
+	/**
+	 * @ticket 40201
+	 * @dataProvider data_get_site_caches
+	 */
+	public function test_clean_blog_cache_with_id( $key, $group ) {
+		$site = get_site( self::$site_ids['make.wordpress.org/'] );
+
+		$replacements = array(
+			'%blog_id%'         => $site->blog_id,
+			'%domain%'          => $site->domain,
+			'%path%'            => $site->path,
+			'%domain_path_key%' => md5( $site->domain . $site->path ),
+		);
+
+		$key = str_replace( array_keys( $replacements ), array_values( $replacements ), $key );
+
+		if ( 'sites' === $group ) { // This needs to be actual data for get_site() lookups.
+			wp_cache_set( $key, (object) $site->to_array(), $group );
+		} else {
+			wp_cache_set( $key, 'something', $group );
+		}
+
+		clean_blog_cache( $site->blog_id );
+		$this->assertFalse( wp_cache_get( $key, $group ) );
+	}
+
 	/**
 	 * @ticket 40201
 	 */
@@ -1122,6 +1148,38 @@ class Tests_Multisite_Site extends WP_UnitTestCase {
 		$this->assertEquals( $old_count, did_action( 'clean_site_cache' ) );
 	}
 
+	/**
+	 * @ticket 40201
+	 */
+	public function test_clean_blog_cache_bails_on_empty_input() {
+		$old_count = did_action( 'clean_site_cache' );
+
+		clean_blog_cache( null );
+		$this->assertEquals( $old_count, did_action( 'clean_site_cache' ) );
+	}
+
+	/**
+	 * @ticket 40201
+	 */
+	public function test_clean_blog_cache_bails_on_non_numeric_input() {
+		$old_count = did_action( 'clean_site_cache' );
+
+		clean_blog_cache( 'something' );
+		$this->assertEquals( $old_count, did_action( 'clean_site_cache' ) );
+	}
+
+	/**
+	 * @ticket 40201
+	 */
+	public function test_clean_blog_cache_works_with_deleted_site() {
+		$site_id = 12345;
+
+		wp_cache_set( $site_id, 'something', 'site-details' );
+
+		clean_blog_cache( $site_id );
+		$this->assertFalse( wp_cache_get( $site_id, 'site-details' ) );
+	}
+
 	/**
 	 * @ticket 40201
 	 * @dataProvider data_get_site_caches