Rename post_states_string to post_states_html and improve phpdoc

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 sta60986tes 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,8 @@ 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.
+	 * @param WP_Post                $post        The current post object.
 	 */
 	return apply_filters( 'display_post_states', $post_states, $post );
 }

tests/phpunit/tests/post/getPostStatus.php

@@ -166,7 +166,7 @@ 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
 	 *
@@ -176,7 +176,7 @@ public function data_get_post_status_after_trashing() {
 	 *
 	 * @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,7 +188,7 @@ public function test_filter_post_states_string_should_enable_post_state_html_out
 		}
 
 		add_filter(
-			'post_states_string',
+			'post_states_html',
 			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.' );
 				$this->assertIsArray( $post_states, 'Expected second filter arg to be an array.' );