Posts, Post Types: Rename new post_states_string filter to post_states_html.

Add examples to the PHPDoc for the filter params.

Developed in #10360

Follow-up to [60986].

Props dmsnell, westonruter.
See #51403.


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

Author: westonruter

src/wp-admin/includes/template.php

@@ -2246,22 +2246,22 @@ function iframe_footer() {
  * @return string Post states string.
  */
 function _post_states( $post, $display = true ) {
-	$post_states        = get_post_states( $post );
-	$post_states_string = '';
+	$post_states      = get_post_states( $post );
+	$post_states_html = '';
 
 	if ( ! empty( $post_states ) ) {
 		$state_count = count( $post_states );
 
 		$i = 0;
 
-		$post_states_string .= ' — ';
+		$post_states_html .= ' — ';
 
 		foreach ( $post_states as $state ) {
 			++$i;
 
 			$separator = ( $i < $state_count ) ? ', ' : '';
 
-			$post_states_string .= "<span class='post-state'>{$state}{$separator}</span>";
+			$post_states_html .= "<span class='post-state'>{$state}{$separator}</span>";
 		}
 	}
 
@@ -2270,17 +2270,19 @@ function _post_states( $post, $display = true ) {
 	 *
 	 * @since 6.9.0
 	 *
-	 * @param string   $post_states_string The post states HTML string.
-	 * @param string[] $post_states        The post states.
-	 * @param WP_Post  $post               The current post object.
+	 * @param string                 $post_states_html All relevant post states combined into an HTML string for display.
+	 *                                                 E.g. `&mdash; <span class='post-state'>Draft, </span><span class='post-state'>Sticky</span>`.
+	 * @param string<string, string> $post_states      A mapping of post state slugs to translated post state labels.
+	 *                                                 E.g. `array( 'draft' => __( 'Draft' ), 'sticky' => __( 'Sticky' ), ... )`.
+	 * @param WP_Post                $post             The current post object.
 	 */
-	$post_states_string = apply_filters( 'post_states_string', $post_states_string, $post_states, $post );
+	$post_states_html = apply_filters( 'post_states_html', $post_states_html, $post_states, $post );
 
 	if ( $display ) {
-		echo $post_states_string;
+		echo $post_states_html;
 	}
 
-	return $post_states_string;
+	return $post_states_html;
 }
 
 /**
@@ -2353,8 +2355,9 @@ function get_post_states( $post ) {
 	 *              are used within the filter, their existence should be checked
 	 *              with `function_exists()` before being used.
 	 *
-	 * @param string[] $post_states An array of post display states.
-	 * @param WP_Post  $post        The current post object.
+	 * @param string<string, string> $post_states A mapping of post state slugs to translated post state labels.
+	 *                                            E.g. `array( 'draft' => __( 'Draft' ), 'sticky' => __( 'Sticky' ), ... )`.
+	 * @param WP_Post                $post        The current post object.
 	 */
 	return apply_filters( 'display_post_states', $post_states, $post );
 }

tests/phpunit/tests/post/getPostStatus.php

@@ -166,17 +166,17 @@ public function data_get_post_status_after_trashing() {
 	}
 
 	/**
-	 * Ensure the `post_states_string` filter works to modify post state output.
+	 * Ensure the `post_states_html` filter works to modify post state output.
 	 *
 	 * @ticket 51403
 	 *
-	 * @dataProvider data_filter_post_states_string_should_enable_post_state_html_output_modification
+	 * @dataProvider data_filter_post_states_html_should_enable_post_state_html_output_modification
 	 *
 	 * @covers ::_post_states
 	 *
 	 * @param string $post_state The post state to test.
 	 */
-	public function test_filter_post_states_string_should_enable_post_state_html_output_modification( $post_state ) {
+	public function test_filter_post_states_html_should_enable_post_state_html_output_modification( $post_state ) {
 		$post = get_post( self::$post_ids[ $post_state ] );
 
 		$original_output = _post_states( $post, false );
@@ -188,13 +188,13 @@ public function test_filter_post_states_string_should_enable_post_state_html_out
 		}
 
 		add_filter(
-			'post_states_string',
-			function ( $post_states_string, $post_states, $filtered_post ) use ( $text_to_append, $post ) {
-				$this->assertIsString( $post_states_string, 'Expected first filter arg to be a string.' );
+			'post_states_html',
+			function ( $post_states_html, $post_states, $filtered_post ) use ( $text_to_append, $post ) {
+				$this->assertIsString( $post_states_html, 'Expected first filter arg to be a string.' );
 				$this->assertIsArray( $post_states, 'Expected second filter arg to be an array.' );
 				$this->assertInstanceOf( WP_Post::class, $filtered_post, 'Expected third filter arg to be a WP_Post' );
 				$this->assertSame( $post->ID, $filtered_post->ID, 'Expected the third filter arg to be the same as the current post.' );
-				return $post_states_string . $text_to_append;
+				return $post_states_html . $text_to_append;
 			},
 			10,
 			3
@@ -206,13 +206,13 @@ function ( $post_states_string, $post_states, $filtered_post ) use ( $text_to_ap
 	}
 
 	/**
-	 * Data provider for test_filter_post_states_string_should_enable_post_state_html_output_modification().
+	 * Data provider for test_filter_post_states_html_should_enable_post_state_html_output_modification().
 	 *
 	 * @return array[] {
 	 *     @type string $post_state The post state to test.
 	 * }
 	 */
-	public static function data_filter_post_states_string_should_enable_post_state_html_output_modification() {
+	public static function data_filter_post_states_html_should_enable_post_state_html_output_modification() {
 		return array(
 			array( 'publish' ),
 			array( 'future' ),