Query: Some documentation and test improvements for update_post_author_caches():

* Make the descriptions for `update_post_author_caches()` and `update_post_caches()` more specific.
* Move the unit test into its own file, for consistency with `update_post_cache()` tests. This also allows for using shared fixtures in case more tests are added in the future.

Follow-up to [53482].

See #55716.

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

src/wp-includes/class-wp-query.php

@@ -3434,9 +3434,11 @@ class WP_Query {
 	 */
 	public function the_post() {
 		global $post;
+
 		if ( ! $this->in_the_loop ) {
 			update_post_author_caches( $this->posts );
 		}
+
 		$this->in_the_loop = true;
 
 		if ( -1 == $this->current_post ) { // Loop has just started.

src/wp-includes/pluggable.php

@@ -143,6 +143,7 @@ if ( ! function_exists( 'cache_users' ) ) :
 		$list = implode( ',', $clean );
 
 		$users = $wpdb->get_results( "SELECT * FROM $wpdb->users WHERE ID IN ($list)" );
+
 		foreach ( $users as $user ) {
 			update_user_caches( $user );
 		}

src/wp-includes/post.php

@@ -7424,11 +7424,11 @@ function clean_post_cache( $post ) {
 }
 
 /**
- * Calls major cache updating functions for list of Post objects.
+ * Updates post, term, and metadata caches for a list of post objects.
  *
  * @since 1.5.0
  *
- * @param WP_Post[] $posts             Array of Post objects
+ * @param WP_Post[] $posts             Array of post objects (passed by reference).
  * @param string    $post_type         Optional. Post type. Default 'post'.
  * @param bool      $update_term_cache Optional. Whether to update the term cache. Default true.
  * @param bool      $update_meta_cache Optional. Whether to update the meta cache. Default true.
@@ -7475,21 +7475,22 @@ function update_post_caches( &$posts, $post_type = 'post', $update_term_cache =
 }
 
 /**
- * Prime post author user caches.
+ * Updates post author user caches for a list of post objects.
  *
  * @since 6.1.0
  *
- * @param WP_Post[] $posts Array of Post objects
+ * @param WP_Post[] $posts Array of post objects.
  */
 function update_post_author_caches( $posts ) {
 	$author_ids = wp_list_pluck( $posts, 'post_author' );
 	$author_ids = array_map( 'absint', $author_ids );
 	$author_ids = array_unique( array_filter( $author_ids ) );
+
 	cache_users( $author_ids );
 }
 
 /**
- * Updates metadata cache for list of post IDs.
+ * Updates metadata cache for a list of post IDs.
  *
  * Performs SQL query to retrieve the metadata for the post IDs and updates the
  * metadata cache for the posts. Therefore, the functions, which call this

tests/phpunit/tests/post/updatePostAuthorCaches.php

@@ -0,0 +1,75 @@
+<?php
+/**
+ * Test `update_post_author_caches()`.
+ *
+ * @package WordPress
+ */
+
+/**
+ * Test class for `update_post_author_caches()`.
+ *
+ * @group post
+ * @group query
+ * @group user
+ *
+ * @covers ::update_post_author_caches
+ */
+class Tests_Post_UpdatePostAuthorCaches extends WP_UnitTestCase {
+
+	/**
+	 * User IDs from the shared fixture.
+	 *
+	 * @var int[]
+	 */
+	public static $user_ids;
+
+	/**
+	 * Post author count.
+	 *
+	 * @var int
+	 */
+	public static $post_author_count = 5;
+
+	/**
+	 * Set up test resources before the class.
+	 *
+	 * @param WP_UnitTest_Factory $factory The unit test factory.
+	 */
+	public static function wpSetupBeforeClass( WP_UnitTest_Factory $factory ) {
+		self::$user_ids = array();
+
+		for ( $i = 0; $i < self::$post_author_count; $i++ ) {
+			self::$user_ids[ $i ] = $factory->user->create();
+			$factory->post->create(
+				array(
+					'post_type'   => 'post',
+					'post_author' => self::$user_ids[ $i ],
+				)
+			);
+		}
+	}
+
+	/**
+	 * @ticket 55716
+	 */
+	public function test_update_post_author_caches() {
+		$action = new MockAction();
+		add_filter( 'update_user_metadata_cache', array( $action, 'filter' ), 10, 2 );
+
+		$q = new WP_Query(
+			array(
+				'post_type'      => 'post',
+				'posts_per_page' => self::$post_author_count,
+			)
+		);
+
+		while ( $q->have_posts() ) {
+			$q->the_post();
+		}
+
+		$args      = $action->get_args();
+		$last_args = end( $args );
+
+		$this->assertSameSets( self::$user_ids, $last_args[1], 'Ensure that user IDs are primed' );
+	}
+}

tests/phpunit/tests/post/updatePostCache.php

@@ -1,12 +1,12 @@
 <?php
 /**
- * Test `wp_update_cache()`.
+ * Test `update_post_cache()`.
  *
  * @package WordPress
  */
 
 /**
- * Test class for `wp_update_cache()`.
+ * Test class for `update_post_cache()`.
  *
  * @group post
  * @group query
@@ -18,7 +18,7 @@ class Tests_Post_UpdatePostCache extends WP_UnitTestCase {
 	/**
 	 * Post IDs from the shared fixture.
 	 *
-	 * @var array
+	 * @var int[]
 	 */
 	public static $post_ids;
 

tests/phpunit/tests/query.php

@@ -620,39 +620,6 @@ class Tests_Query extends WP_UnitTestCase {
 		$this->assertSame( array( $p2 ), $q->posts );
 	}
 
-	/**
-	 * @ticket 55716
-	 */
-	public function test_prime_user_cache() {
-		$action = new MockAction();
-		add_filter( 'update_user_metadata_cache', array( $action, 'filter' ), 10, 2 );
-		$user_ids = array();
-		$count    = 5;
-		for ( $i = 0; $i < $count; $i ++ ) {
-			$user_ids[ $i ] = self::factory()->user->create();
-			self::factory()->post->create(
-				array(
-					'post_type'   => 'post',
-					'post_author' => $user_ids[ $i ],
-				)
-			);
-		}
-
-		$q = new WP_Query(
-			array(
-				'post_type'      => 'post',
-				'posts_per_page' => $count,
-			)
-		);
-		while ( $q->have_posts() ) {
-			$q->the_post();
-		}
-
-		$args      = $action->get_args();
-		$last_args = end( $args );
-		$this->assertSameSets( $user_ids, $last_args[1], 'Ensure that user ids are primed' );
-	}
-
 	/**
 	 * @ticket 35601
 	 */