Changeset 53480 for trunk/src/wp-includes/media.php

Timestamp:

06/09/2022 05:29:57 AM (2 years ago)

Author:

peterwilsoncc

Message:

Media: Add decoding="async" to image attributes.

Dynamically add decoding="async" to image tags on the front end of a site to instruct browsers to download them in parallel.

Modifies wp_get_attachment_image(), get_avatar() to include the attribute by default. Modifies wp_filter_content_tags() to add the attribute during the front-end render of the site.

Introduces wp_img_tag_add_decoding_attr() to take an image tag and modify it to include the attribute. Introduces the filter wp_img_tag_add_decoding_attr used to define the default value for the attribute.

Props adamsilverstein, ayeshrajans, costdev, flixos90, hellofromtonya, isaumya, michaelbourne, mihai2u, mitogh, sergiomdgomes, spacedmonkey, westonruter, peterwilsoncc.
Fixes #53232.

File:

• trunk/src/wp-includes/media.php (modified) (4 diffs)

trunk/src/wp-includes/media.php

@@ -1012 +1012 @@
  *     Optional. Attributes for the image markup.
  *
- *     @type string       $src     Image attachment URL.
- *     @type string       $class   CSS class name or space-separated list of classes.
- *                                 Default `attachment-$size_class size-$size_class`,
- *                                 where `$size_class` is the image size being requested.
- *     @type string       $alt     Image description for the alt attribute.
- *     @type string       $srcset  The 'srcset' attribute value.
- *     @type string       $sizes   The 'sizes' attribute value.
- *     @type string|false $loading The 'loading' attribute value. Passing a value of false
- *                                 will result in the attribute being omitted for the image.
- *                                 Defaults to 'lazy', depending on wp_lazy_loading_enabled().
+ *     @type string       $src      Image attachment URL.
+ *     @type string       $class    CSS class name or space-separated list of classes.
+ *                                  Default `attachment-$size_class size-$size_class`,
+ *                                  where `$size_class` is the image size being requested.
+ *     @type string       $alt      Image description for the alt attribute.
+ *     @type string       $srcset   The 'srcset' attribute value.
+ *     @type string       $sizes    The 'sizes' attribute value.
+ *     @type string|false $loading  The 'loading' attribute value. Passing a value of false
+ *                                  will result in the attribute being omitted for the image.
+ *                                  Defaults to 'lazy', depending on wp_lazy_loading_enabled().
+ *     @type string       $decoding The 'decoding' attribute value. Possible values are
+ *                                  'async' (default), 'sync', or 'auto'.
  * }
  * @return string HTML img element or empty string on failure.
@@ -1041 +1043 @@
 
         $default_attr = array(
-            'src'   => $src,
-            'class' => "attachment-$size_class size-$size_class",
-            'alt'   => trim( strip_tags( get_post_meta( $attachment_id, '_wp_attachment_image_alt', true ) ) ),
+            'src'      => $src,
+            'class'    => "attachment-$size_class size-$size_class",
+            'alt'      => trim( strip_tags( get_post_meta( $attachment_id, '_wp_attachment_image_alt', true ) ) ),
+            'decoding' => 'async',
         );
 
@@ -1844 +1847 @@
             }
 
+            // Add 'decoding=async' attribute unless a 'decoding' attribute is already present.
+            if ( ! str_contains( $filtered_image, ' decoding=' ) ) {
+                $filtered_image = wp_img_tag_add_decoding_attr( $filtered_image, $context );
+            }
+
             /**
              * Filters an img tag within the content for a given context.
@@ -1930 +1938 @@
 
         return str_replace( '<img', '<img loading="' . esc_attr( $value ) . '"', $image );
+    }
+
+    return $image;
+}
+
+/**
+ * Add `decoding` attribute to an `img` HTML tag.
+ *
+ * The `decoding` attribute allows developers to indicate whether the
+ * browser can decode the image off the main thread (`async`), on the
+ * main thread (`sync`) or as determined by the browser (`auto`).
+ *
+ * By default WordPress adds `decoding="async"` to images but developers
+ * can use the {@see 'wp_img_tag_add_decoding_attr'} filter to modify this
+ * to remove the attribute or set it to another accepted value.
+ *
+ * @since 6.1.0
+ *
+ * @param string $image   The HTML `img` tag where the attribute should be added.
+ * @param string $context Additional context to pass to the filters.
+ *
+ * @return string Converted `img` tag with `decoding` attribute added.
+ */
+function wp_img_tag_add_decoding_attr( $image, $context ) {
+    /**
+     * Filters the `decoding` attribute value to add to an image. Default `async`.
+     *
+     * Returning a falsey value will omit the attribute.
+     *
+     * @since 6.1.0
+     *
+     * @param string|false|null $value   The `decoding` attribute value. Returning a falsey value will result in
+     *                                   the attribute being omitted for the image. Otherwise, it may be:
+     *                                   'async' (default), 'sync', or 'auto'.
+     * @param string            $image   The HTML `img` tag to be filtered.
+     * @param string            $context Additional context about how the function was called or where the img tag is.
+     */
+    $value = apply_filters( 'wp_img_tag_add_decoding_attr', 'async', $image, $context );
+    if ( in_array( $value, array( 'async', 'sync', 'auto' ), true ) ) {
+        $image = str_replace( '<img ', '<img decoding="' . esc_attr( $value ) . '" ', $image );
     }