Changeset 55821

Timestamp:

05/17/2023 06:29:41 PM (18 months ago)

Author:

flixos90

Message:

Media: Introduce wp_get_attachment_image_context filter.

Since WordPress 5.9, a "context" value of "wp_get_attachment_image" has been used in the wp_get_attachment_image() function to provide context to underlying functions where that is relevant, e.g. wp_get_loading_attr_default(). Since that value used to be not customizable, it required a workaround in get_the_post_thumbnail() to avoid calling those functions in wp_get_attachment_image(), which resulted in unnecessary complexity and was prone to errors.

This changeset introduces a wp_get_attachment_image_context filter and leverages it with private filter callback functions that are leveraged by default when get_the_post_thumbnail() is called. This avoids the need for the previous workaround and furthermore provides flexibility for other callers of wp_get_attachment_image() to provide their own contexts.

Props flixos90, costdev, thekt12, westonruter, spacedmonkey.
Fixes #58212.

Location:

trunk

Files:

• src/wp-includes/default-filters.php (modified) (1 diff)
• src/wp-includes/media.php (modified) (2 diffs)
• src/wp-includes/post-thumbnail-template.php (modified) (1 diff)
• tests/phpunit/tests/media.php (modified) (1 diff)
• tests/phpunit/tests/post/thumbnails.php (modified) (1 diff)

trunk/src/wp-includes/default-filters.php

@@ -445 +445 @@
 add_action( 'delete_post', '_wp_delete_customize_changeset_dependent_auto_drafts' );
 
-// Post Thumbnail CSS class filtering.
+// Post Thumbnail specific image filtering.
 add_action( 'begin_fetch_post_thumbnail_html', '_wp_post_thumbnail_class_filter_add' );
 add_action( 'end_fetch_post_thumbnail_html', '_wp_post_thumbnail_class_filter_remove' );
+add_action( 'begin_fetch_post_thumbnail_html', '_wp_post_thumbnail_context_filter_add' );
+add_action( 'end_fetch_post_thumbnail_html', '_wp_post_thumbnail_context_filter_remove' );
 
 // Redirect old slugs.

trunk/src/wp-includes/media.php

@@ -1051 +1051 @@
         );
 
+        /**
+         * Filters the context in which wp_get_attachment_image() is used.
+         *
+         * @since 6.3.0
+         *
+         * @param string $context The context. Default 'wp_get_attachment_image'.
+         */
+        $context = apply_filters( 'wp_get_attachment_image_context', 'wp_get_attachment_image' );
+
         // Add `loading` attribute.
-        if ( wp_lazy_loading_enabled( 'img', 'wp_get_attachment_image' ) ) {
-            $default_attr['loading'] = wp_get_loading_attr_default( 'wp_get_attachment_image' );
+        if ( wp_lazy_loading_enabled( 'img', $context ) ) {
+            $default_attr['loading'] = wp_get_loading_attr_default( $context );
         }
 
@@ -2169 +2178 @@
 function _wp_post_thumbnail_class_filter_remove( $attr ) {
     remove_filter( 'wp_get_attachment_image_attributes', '_wp_post_thumbnail_class_filter' );
+}
+
+/**
+ * Overrides the context used in {@see wp_get_attachment_image()}. Internal use only.
+ *
+ * Uses the {@see 'begin_fetch_post_thumbnail_html'} and {@see 'end_fetch_post_thumbnail_html'}
+ * action hooks to dynamically add/remove itself so as to only filter post thumbnails.
+ *
+ * @ignore
+ * @since 6.3.0
+ * @access private
+ *
+ * @param string $context The context for rendering an attachment image.
+ * @return string Modified context set to 'the_post_thumbnail'.
+ */
+function _wp_post_thumbnail_context_filter( $context ) {
+    return 'the_post_thumbnail';
+}
+
+/**
+ * Adds the '_wp_post_thumbnail_context_filter' callback to the 'wp_get_attachment_image_context'
+ * filter hook. Internal use only.
+ *
+ * @ignore
+ * @since 6.3.0
+ * @access private
+ */
+function _wp_post_thumbnail_context_filter_add() {
+    add_filter( 'wp_get_attachment_image_context', '_wp_post_thumbnail_context_filter' );
+}
+
+/**
+ * Removes the '_wp_post_thumbnail_context_filter' callback from the 'wp_get_attachment_image_context'
+ * filter hook. Internal use only.
+ *
+ * @ignore
+ * @since 6.3.0
+ * @access private
+ */
+function _wp_post_thumbnail_context_filter_remove() {
+    remove_filter( 'wp_get_attachment_image_context', '_wp_post_thumbnail_context_filter' );
 }
 

trunk/src/wp-includes/post-thumbnail-template.php

@@ -187 +187 @@
         }
 
-        // Add `loading` attribute.
-        if ( wp_lazy_loading_enabled( 'img', 'the_post_thumbnail' ) ) {
-            // Get the 'loading' attribute value to use as default, taking precedence over the default from
-            // `wp_get_attachment_image()`.
-            $loading = wp_get_loading_attr_default( 'the_post_thumbnail' );
-
-            // Add the default to the given attributes unless they already include a 'loading' directive.
-            if ( empty( $attr ) ) {
-                $attr = array( 'loading' => $loading );
-            } elseif ( is_array( $attr ) && ! array_key_exists( 'loading', $attr ) ) {
-                $attr['loading'] = $loading;
-            } elseif ( is_string( $attr ) && ! preg_match( '/(^|&)loading=/', $attr ) ) {
-                $attr .= '&loading=' . $loading;
-            }
-        }
-
         $html = wp_get_attachment_image( $post_thumbnail_id, $size, false, $attr );
 

trunk/tests/phpunit/tests/media.php

@@ -3965 +3965 @@
 
     /**
+     * Tests that `wp_get_attachment_image()` uses the correct default context.
+     *
+     * @ticket 58212
+     *
+     * @covers ::wp_get_attachment_image()
+     */
+    public function test_wp_get_attachment_image_context_filter_default() {
+        $last_context = '';
+        $this->track_last_attachment_image_context( $last_context );
+
+        wp_get_attachment_image( self::$large_id );
+        $this->assertSame( 'wp_get_attachment_image', $last_context );
+    }
+
+    /**
+     * Tests that `wp_get_attachment_image()` allows overriding the context via filter.
+     *
+     * @ticket 58212
+     *
+     * @covers ::wp_get_attachment_image()
+     */
+    public function test_wp_get_attachment_image_context_filter_value_is_passed_correctly() {
+        $last_context = '';
+        $this->track_last_attachment_image_context( $last_context );
+
+        // Add a filter that modifies the context.
+        add_filter(
+            'wp_get_attachment_image_context',
+            static function() {
+                return 'my_custom_context';
+            }
+        );
+
+        wp_get_attachment_image( self::$large_id );
+        $this->assertSame( 'my_custom_context', $last_context );
+    }
+
+    /**
+     * Helper method to keep track of the last context returned by the 'wp_get_attachment_image_context' filter.
+     *
+     * The method parameter is passed by reference and therefore will always contain the last context value.
+     *
+     * @param mixed $last_context Variable to track last context. Passed by reference.
+     */
+    private function track_last_attachment_image_context( &$last_context ) {
+        add_filter(
+            'wp_get_attachment_image_context',
+            static function( $context ) use ( &$last_context ) {
+                $last_context = $context;
+                return $context;
+            },
+            11
+        );
+    }
+
+    /**
      * Add threshold to create a `-scaled` output image for testing.
      */

trunk/tests/phpunit/tests/post/thumbnails.php

@@ -451 +451 @@
     }
 
+    /**
+     * Tests that `_wp_post_thumbnail_context_filter()` returns 'the_post_thumbnail'.
+     *
+     * @ticket 58212
+     *
+     * @covers::_wp_post_thumbnail_context_filter
+     */
+    public function test_wp_post_thumbnail_context_filter_should_return_the_post_thumbnail() {
+        $this->assertSame( 'the_post_thumbnail', _wp_post_thumbnail_context_filter( 'wp_get_attachment_image' ) );
+    }
+
+    /**
+     * Tests that `::_wp_post_thumbnail_context_filter_add` adds a filter to override the context
+     * used in `wp_get_attachment_image()`.
+     *
+     * @ticket 58212
+     *
+     * @covers ::_wp_post_thumbnail_context_filter_add
+     */
+    public function test_wp_post_thumbnail_context_filter_add_should_add_the_filter() {
+        $last_context = '';
+        $this->track_last_attachment_image_context( $last_context );
+
+        _wp_post_thumbnail_context_filter_add();
+        wp_get_attachment_image( self::$attachment_id );
+
+        $this->assertSame( 'the_post_thumbnail', $last_context );
+    }
+
+    /**
+     * Tests that `_wp_post_thumbnail_context_filter_remove()` removes a filter to override the context
+     * used in `wp_get_attachment_image()`.
+     *
+     * @ticket 58212
+     *
+     * @covers ::_wp_post_thumbnail_context_filter_remove
+     */
+    public function test_wp_post_thumbnail_context_filter_remove_should_remove_the_filter() {
+        $last_context = '';
+        $this->track_last_attachment_image_context( $last_context );
+
+        _wp_post_thumbnail_context_filter_add();
+        wp_get_attachment_image( self::$attachment_id );
+
+        // Verify that the filter has been added before testing that it has been removed.
+        $this->assertSame(
+            'the_post_thumbnail',
+            $last_context,
+            'The filter was not added.'
+        );
+
+        _wp_post_thumbnail_context_filter_remove();
+
+        // The context should no longer be modified by the filter.
+        wp_get_attachment_image( self::$attachment_id );
+
+        $this->assertSame(
+            'wp_get_attachment_image',
+            $last_context,
+            'The filter was not removed.'
+        );
+    }
+
+    /**
+     * Tests that `get_the_post_thumbnail()` uses the 'the_post_thumbnail' context.
+     *
+     * @ticket 58212
+     *
+     * @covers ::get_the_post_thumbnail
+     */
+    public function test_get_the_post_thumbnail_should_use_the_post_thumbnail_context() {
+        $last_context = '';
+        $this->track_last_attachment_image_context( $last_context );
+
+        set_post_thumbnail( self::$post, self::$attachment_id );
+        get_the_post_thumbnail( self::$post );
+
+        $this->assertSame( 'the_post_thumbnail', $last_context );
+    }
+
+    /**
+     * Tests that `get_the_post_thumbnail()` restores the context afterwards.
+     *
+     * @ticket 58212
+     *
+     * @covers ::get_the_post_thumbnail
+     */
+    public function test_get_the_post_thumbnail_should_remove_the_post_thumbnail_context_afterwards() {
+        $last_context = '';
+        $this->track_last_attachment_image_context( $last_context );
+
+        set_post_thumbnail( self::$post, self::$attachment_id );
+        get_the_post_thumbnail( self::$post );
+
+        // Verify that the context was overridden before testing that it has been restored.
+        $this->assertSame(
+            'the_post_thumbnail',
+            $last_context,
+            'The context was not overridden.'
+        );
+
+        // The context should no longer be overridden.
+        wp_get_attachment_image( self::$attachment_id );
+
+        $this->assertSame(
+            'wp_get_attachment_image',
+            $last_context,
+            'The context was not restored.'
+        );
+    }
+
+    /**
+     * Helper method to keep track of the last context returned by the 'wp_get_attachment_image_context' filter.
+     *
+     * The method parameter is passed by reference and therefore will always contain the last context value.
+     *
+     * @param mixed $last_context Variable to track last context. Passed by reference.
+     */
+    private function track_last_attachment_image_context( &$last_context ) {
+        add_filter(
+            'wp_get_attachment_image_context',
+            static function( $context ) use ( &$last_context ) {
+                $last_context = $context;
+                return $context;
+            },
+            11
+        );
+    }
+
     public function filter_post_thumbnail_size( $size, $post_id ) {
         if ( is_array( $this->current_size_filter_data ) && isset( $this->current_size_filter_data[ $post_id ] ) ) {