Changeset 60993

Timestamp:

10/20/2025 09:43:10 PM (11 months ago)

Author:

westonruter

Message:

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

Add examples to the PHPDoc for the filter params.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/10360

Follow-up to [60986].

Props dmsnell, westonruter.
See #51403.

Location:

trunk

Files:

• src/wp-admin/includes/template.php (modified) (5 diffs)
• tests/phpunit/tests/post/getPostStatus.php (modified) (5 diffs)

trunk/src/wp-admin/includes/template.php

@@ -2247 +2247 @@
  */
 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 ) ) {
@@ -2255 +2255 @@
                 $i = 0;
 
-                $post_states_string .= ' — ';
+                $post_states_html .= ' — ';
 
                 foreach ( $post_states as $state ) {
@@ -2262 +2262 @@
                         $separator = ( $i < $state_count ) ? ', ' : '';
 
-                        $post_states_string .= "<span class='post-state'>{$state}{$separator}</span>";
+                        $post_states_html .= "<span class='post-state'>{$state}{$separator}</span>";
                 }
         }
@@ -2271 +2271 @@
          * @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;
-        }
-
-        return $post_states_string;
+                echo $post_states_html;
+        }
+
+        return $post_states_html;
 }
 
@@ -2354 +2356 @@
          *              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 );

trunk/tests/phpunit/tests/post/getPostStatus.php

@@ -167 +167 @@
 
         /**
-         * 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
@@ -177 +177 @@
          * @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 ] );
 
@@ -189 +189 @@
 
                 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,
@@ -207 +207 @@
 
         /**
-         * 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[] {
@@ -213 +213 @@
          * }
          */
-        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' ),