Changeset 62698

Timestamp:

07/12/2026 09:04:58 PM (2 months ago)

Author:

joedolson

Message:

Media: Ensure figcaption/figure IDs are unique.

Using the same image multiple times with a figure and fig caption would result in duplicate IDs, creating unclear relationships and breaking 3rd party expectations for anchor targets. Check id attributes and append a counter to ensure each attribute is unique, while retaining the current expectation of a counter-less ID attribute for the first instance. Update tests to verify.

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

Props steelwagstaff, westonruter, jamesbregenzer, joedolson, mukesh27.
Fixes #65315.

Location:

trunk

Files:

• src/wp-includes/media.php (modified) (2 diffs)
• tests/phpunit/tests/media.php (modified) (2 diffs)

trunk/src/wp-includes/media.php

@@ -2657 +2657 @@
         }
 
+        /**
+         * @var array{
+         *     id: string,
+         *     caption_id: string,
+         *     align: string,
+         *     width: string,
+         *     caption: string,
+         *     class: string,
+         * } $atts
+         */
         $atts = shortcode_atts(
                 array(
@@ -2676 +2686 @@
         }
 
-        $id          = '';
-        $caption_id  = '';
-        $describedby = '';
+        $id               = '';
+        $caption_id       = '';
+        $describedby      = '';
+        $unique_id_value  = '';
+        $caption_id_value = '';
 
         if ( $atts['id'] ) {
-                $atts['id'] = sanitize_html_class( $atts['id'] );
-                $id         = 'id="' . esc_attr( $atts['id'] ) . '" ';
+                $atts['id']      = sanitize_html_class( $atts['id'] );
+                $unique_id_value = (string) preg_replace( '/-1$/', '', wp_unique_prefixed_id( $atts['id'] . '-' ) );
+                $id              = 'id="' . esc_attr( $unique_id_value ) . '" ';
         }
 
         if ( $atts['caption_id'] ) {
+                // User explicitly provided a caption_id - make it unique.
                 $atts['caption_id'] = sanitize_html_class( $atts['caption_id'] );
-        } elseif ( $atts['id'] ) {
-                $atts['caption_id'] = 'caption-' . str_replace( '_', '-', $atts['id'] );
-        }
-
-        if ( $atts['caption_id'] ) {
-                $caption_id  = 'id="' . esc_attr( $atts['caption_id'] ) . '" ';
-                $describedby = 'aria-describedby="' . esc_attr( $atts['caption_id'] ) . '" ';
+                $caption_id_value   = preg_replace( '/-1$/', '', wp_unique_prefixed_id( $atts['caption_id'] . '-' ) );
+        } elseif ( $unique_id_value ) {
+                // Derive from the already-unique figure ID - guaranteed unique, no need for second call.
+                $caption_id_value = 'caption-' . str_replace( '_', '-', $unique_id_value );
+        }
+
+        if ( $caption_id_value ) {
+                $caption_id  = 'id="' . esc_attr( $caption_id_value ) . '" ';
+                $describedby = 'aria-describedby="' . esc_attr( $caption_id_value ) . '" ';
         }
 

trunk/tests/phpunit/tests/media.php

@@ -270 +270 @@
                 );
                 $this->assertSame( 1, substr_count( $result, 'wp-caption &myAlignment' ) );
-                $this->assertSame( 1, substr_count( $result, 'id="myId"' ) );
+                $this->assertSame( 1, preg_match( '/id="myId(?:[0-9]+)?"/', $result ) );
                 $this->assertSame( 1, substr_count( $result, self::CAPTION ) );
         }
@@ -366 +366 @@
                 );
 
-                $this->assertSame( 1, substr_count( $result, 'aria-describedby="caption-myId"' ) );
+                $this->assertMatchesRegularExpression( '/aria-describedby="caption-myId(?:-[0-9]+)?"/', $result );
+        }
+
+        /**
+         * Tests that both figure and figcaption IDs are unique for multiple caption instances.
+         *
+         * When the same image with the same or different captions appears multiple
+         * times on a page, each figure and figcaption should receive a unique ID to
+         * maintain HTML validity and accessibility.
+         *
+         * @ticket 65315
+         *
+         * @covers ::img_caption_shortcode
+         */
+        public function test_img_caption_shortcode_unique_ids_per_instance(): void {
+                /*
+                 * Important: The id part of this must be unique among unit tests, or else the test will fail due to
+                 * wp_unique_prefixed_id() not returning the expected increment.
+                 */
+                $id         = 'attachment_65315';
+                $caption_id = 'caption_attachment_65315';
+
+                // First instance with caption "My caption".
+                $result_1 = img_caption_shortcode(
+                        array(
+                                'width'      => 20,
+                                'id'         => $id,
+                                'caption'    => 'My caption',
+                                'caption_id' => $caption_id,
+                        ),
+                        self::IMG_CONTENT . 'My caption'
+                );
+
+                // Second instance - identical to first.
+                $result_2 = img_caption_shortcode(
+                        array(
+                                'width'      => 20,
+                                'id'         => $id,
+                                'caption'    => 'My caption',
+                                'caption_id' => $caption_id,
+                        ),
+                        self::IMG_CONTENT . 'My caption'
+                );
+
+                // Third instance - same image, different caption.
+                $result_3 = img_caption_shortcode(
+                        array(
+                                'width'      => 20,
+                                'id'         => $id,
+                                'caption'    => 'Different caption',
+                                'caption_id' => $caption_id,
+                        ),
+                        self::IMG_CONTENT . 'Different caption'
+                );
+
+                // Extract the figure (caption wrapper) and caption text IDs from each instance.
+                $figure_id_1  = $this->get_id_of_first_tag_with_class( $result_1, 'wp-caption' );
+                $figure_id_2  = $this->get_id_of_first_tag_with_class( $result_2, 'wp-caption' );
+                $figure_id_3  = $this->get_id_of_first_tag_with_class( $result_3, 'wp-caption' );
+                $caption_id_1 = $this->get_id_of_first_tag_with_class( $result_1, 'wp-caption-text' );
+                $caption_id_2 = $this->get_id_of_first_tag_with_class( $result_2, 'wp-caption-text' );
+                $caption_id_3 = $this->get_id_of_first_tag_with_class( $result_3, 'wp-caption-text' );
+
+                // Figure IDs should all exist.
+                $this->assertNotEmpty( $figure_id_1, 'First figure should have an ID' );
+                $this->assertNotEmpty( $figure_id_2, 'Second figure should have an ID' );
+                $this->assertNotEmpty( $figure_id_3, 'Third figure should have an ID' );
+
+                // Figure IDs should all be different (each instance gets unique ID).
+                $this->assertNotSame( $figure_id_1, $figure_id_2, 'First and second figures should have different IDs even with identical content' );
+                $this->assertNotSame( $figure_id_2, $figure_id_3, 'Second and third figures should have different IDs' );
+                $this->assertNotSame( $figure_id_1, $figure_id_3, 'First and third figures should have different IDs' );
+
+                // The first Figure ID should be identical to the supplied ID, and the others should have unique suffixes.
+                $this->assertSame( $id, $figure_id_1 );
+                $this->assertSame( "$id-2", $figure_id_2 );
+                $this->assertSame( "$id-3", $figure_id_3 );
+
+                // Caption IDs should all exist.
+                $this->assertNotEmpty( $caption_id_1, 'First caption should have an ID' );
+                $this->assertNotEmpty( $caption_id_2, 'Second caption should have an ID' );
+                $this->assertNotEmpty( $caption_id_3, 'Third caption should have an ID' );
+
+                // Caption IDs should all be different (each instance gets unique ID).
+                $this->assertNotSame( $caption_id_1, $caption_id_2, 'First and second captions should have different IDs even with identical content' );
+                $this->assertNotSame( $caption_id_2, $caption_id_3, 'Second and third captions should have different IDs' );
+                $this->assertNotSame( $caption_id_1, $caption_id_3, 'First and third captions should have different IDs' );
+
+                // The first Caption ID should have no.
+                $this->assertSame( $caption_id, $caption_id_1 );
+                $this->assertSame( "$caption_id-2", $caption_id_2 );
+                $this->assertSame( "$caption_id-3", $caption_id_3 );
+        }
+
+        /**
+         * Returns the `id` attribute of the first tag bearing the given class name.
+         *
+         * @param string $html       Markup to search.
+         * @param string $class_name Class name to locate the tag by.
+         * @return string|null The tag's `id` value, or null if no matching tag or `id` is found.
+         */
+        private function get_id_of_first_tag_with_class( string $html, string $class_name ): ?string {
+                $processor = new WP_HTML_Tag_Processor( $html );
+
+                if ( ! $processor->next_tag( array( 'class_name' => $class_name ) ) ) {
+                        return null;
+                }
+
+                $id = $processor->get_attribute( 'id' );
+
+                return is_string( $id ) ? $id : null;
         }