Posts, Post Types: Add post_states_string filter for HTML string of post states.

Developed in #10000

Props paulbonneau, mukesh27, westonruter, SirLouen, dmsnell, brandbrilliance, shsajalchowdhury, aialvi, ugyensupport.
Fixes #51403.


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

Author: westonruter

src/wp-admin/includes/template.php

@@ -2265,6 +2265,17 @@ function _post_states( $post, $display = true ) {
 		}
 	}
 
+	/**
+	 * Filters the HTML string of post states.
+	 *
+	 * @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.
+	 */
+	$post_states_string = apply_filters( 'post_states_string', $post_states_string, $post_states, $post );
+
 	if ( $display ) {
 		echo $post_states_string;
 	}

tests/phpunit/tests/post/getPostStatus.php

@@ -164,4 +164,62 @@ public function data_get_post_status_after_trashing() {
 			array( 'delete-attachment', 'publish', 'publish' ),
 		);
 	}
+
+	/**
+	 * Ensure the `post_states_string` filter works to modify post state output.
+	 *
+	 * @ticket 51403
+	 *
+	 * @dataProvider data_filter_post_states_string_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 ) {
+		$post = get_post( self::$post_ids[ $post_state ] );
+
+		$original_output = _post_states( $post, false );
+
+		if ( count( get_post_states( $post ) ) === 0 ) {
+			$text_to_append = '&mdash; <span class="post-state">Sample state</span>';
+		} else {
+			$text_to_append = '<span class="post-state">, Sample state</span>';
+		}
+
+		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.' );
+				$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;
+			},
+			10,
+			3
+		);
+
+		$output = _post_states( $post, false );
+
+		$this->assertSame( $original_output . $text_to_append, $output, 'Expected text to be appended to the original output.' );
+	}
+
+	/**
+	 * Data provider for test_filter_post_states_string_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() {
+		return array(
+			array( 'publish' ),
+			array( 'future' ),
+			array( 'draft' ),
+			array( 'auto-draft' ),
+			array( 'trash' ),
+			array( 'private' ),
+		);
+	}
 }