Ticket #30180: 30180.2.2.diff

src/wp-includes/general-template.php

@@ -966 +966 @@
                  * If the logo alt attribute is empty, get the site title and explicitly
                  * pass it to the attributes used by wp_get_attachment_image().
                  */
-                $image_alt = get_post_meta( $custom_logo_id, '_wp_attachment_image_alt', true );
+                $image_alt = wp_get_attachment_image_attr( $custom_logo_id, 'alt' );
                 if ( empty( $image_alt ) ) {
                         $custom_logo_attr['alt'] = get_bloginfo( 'name', 'display' );
                 }

src/wp-includes/media.php

@@ -968 +968 @@
 }
 
 /**
+ * Retrieve an image attribute value.
+ *
+ * Retrieve either a single image attribute value or all relevant attribute values. The possible
+ * values are `alt`, `description`, `caption`, `src`, `width`, `height`, `srcset`, `sizes`, `class`. When
+ * retrieving src, width, height, srcset, sizes, or class, you can specify the size of the image to retrieve
+ * in the args parameter. Passing in an empty attribute value will return all relevant values.
+ *
+ * @since 5.X
+ *
+ * @param int          $attachment_id Image attachment ID.
+ * @param string|array $attribute     Image attribute to retrieve. An empty value or `all` will retrieve all values.
+ * @param array        $args          Optional. Array of attributes for the function. Currently only
+ *                                    supports 'size' for the image source.
+ * @return null|string|array          Returns the value of the attribute or attributes requested. A single
+ *                                    attribute will return a single value. An array of attributes or no
+ *                                    attribute will return an array of values.
+ */
+function wp_get_attachment_image_attr( $attachment_id, $attribute = array(), $args = array() ) {
+        $image = get_post( $attachment_id );
+
+        // If this isn't an image, bail early with null.
+        if ( empty( $image ) ) {
+                return null;
+        }
+
+        $values = array();
+        $names  = array();
+
+        if ( empty( $attribute ) || 'all' === $attribute ) {
+                // If an empty value is passed for the attr name, return all our attributes.
+                $names = array(
+                        'alt',
+                        'description',
+                        'caption',
+                        'src',
+                        'width',
+                        'height',
+                        'srcset',
+                        'sizes',
+                        'class',
+                );
+        } elseif ( is_string( $attribute ) ) {
+                // If the attribute name is a string, convert it to an array.
+                $names = array( $attribute );
+        }
+
+        // Get a valid args array.
+        $default_args = array(
+                'icon' => false,
+                'size' => null,
+        );
+
+        $args = wp_parse_args( $args, $default_args );
+
+        // Loop through our names and get the value for each one.
+        foreach ( $names as $name ) {
+                switch ( $name ) {
+                        case 'alt':
+                                $values[ $name ] = get_post_meta( $attachment_id, '_wp_attachment_image_alt', true );
+                                break;
+
+                        case 'description':
+                                $values[ $name ] = $image->post_content;
+                                break;
+
+                        case 'caption':
+                                $values[ $name ] = $image->post_excerpt;
+                                break;
+
+                        case 'src':
+                                if ( ! isset( $image_src ) ) {
+                                        $image_src = wp_get_attachment_image_src( $attachment_id, $args['size'], $args['icon'] );
+                                }
+
+                                $values[ $name ] = $image_src[0];
+                                break;
+
+                        case 'width':
+                                if ( ! isset( $image_src ) ) {
+                                        $image_src = wp_get_attachment_image_src( $attachment_id, $args['size'], $args['icon'] );
+                                }
+
+                                $values[ $name ] = $image_src[1];
+                                break;
+
+                        case 'height':
+                                if ( ! isset( $image_src ) ) {
+                                        $image_src = wp_get_attachment_image_src( $attachment_id, $args['size'], $args['icon'] );
+                                }
+
+                                $values[ $name ] = $image_src[2];
+                                break;
+
+                        case 'srcset':
+                                $values[ $name ] = wp_get_attachment_image_srcset( $attachment_id, $args['size'] );
+                                break;
+
+                        case 'sizes':
+                                $values[ $name ] = wp_get_attachment_image_sizes( $attachment_id, $args['size'] );
+                                break;
+
+                        case 'class':
+                                $size_class = $args['size'];
+
+                                if ( is_array( $size_class ) ) {
+                                        $size_class = join( 'x', $size_class );
+                                }
+
+                                $values[ $name ] = 'attachment-' . $size_class . ' size-' . $size_class;
+                                break;
+                }
+        }
+
+        /**
+         * Filters the image attr result.
+         *
+         * Will apply to all image attribute types.
+         *
+         * @since 5.x
+         *
+         * @param string|int $values         Value of the attribute.
+         * @param int        $attachment_id Image attachment ID.
+         * @param string     $name     Name of the attribute being retrieved.
+         * @param array      $args          Arguments passed into the function.
+         */
+        $values = apply_filters( 'wp_get_attachment_image_attr', $values, $attachment_id, $attribute, $args );
+
+        // If we didn't request a single attribute, we're done.
+        if ( is_array( $attribute ) || empty( $attribute ) || 'all' === $attribute ) {
+                return $values;
+        }
+
+        if ( ! empty( $values[ $attribute ] ) ) {
+                $value = $values[ $attribute ];
+        } else {
+                $value = null;
+        }
+
+        /**
+         * Filters the image attr result.
+         *
+         * This is a dynamic filter that will generate a distinct filter for each attribute type.
+         * It only runs if the requested attribute is a string.
+         *
+         * <code>
+         * <?php
+         * function filter_alt_text( $alt ) {
+         *     $alt = $alt . ' Extra content';
+         *     return $alt;
+         * }
+         * add_filter( 'wp_get_attachment_image_attr_alt', 'filter_alt_text' );
+         * </code>
+         *
+         * @since 5.x
+         *
+         * @param string|int $value         Value of the attribute.
+         * @param int        $attachment_id Image attachment ID.
+         * @param array      $args          Arguments passed into the function.
+         */
+        $value = apply_filters( 'wp_get_attachment_image_attr_' . $attribute, $value, $attachment_id, $args );
+
+        return $value;
+}
+
+/**
  * Get an HTML img element representing an image attachment
  *
  * While `$size` will accept an array, it is better to register a size with
@@ -985 +1150 @@
  * @return string HTML img element or empty string on failure.
  */
 function wp_get_attachment_image( $attachment_id, $size = 'thumbnail', $icon = false, $attr = '' ) {
-        $html  = '';
-        $image = wp_get_attachment_image_src( $attachment_id, $size, $icon );
-        if ( $image ) {
-                list($src, $width, $height) = $image;
-                $hwstring                   = image_hwstring( $width, $height );
-                $size_class                 = $size;
-                if ( is_array( $size_class ) ) {
-                        $size_class = join( 'x', $size_class );
-                }
-                $attachment   = get_post( $attachment_id );
-                $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 ) ) ),
-                );
+        $html = '';
 
-                $attr = wp_parse_args( $attr, $default_attr );
+        $image_attr_args = array(
+                'size' => $size,
+                'icon' => $icon,
+        );
 
-                // Generate 'srcset' and 'sizes' if not already present.
-                if ( empty( $attr['srcset'] ) ) {
-                        $image_meta = wp_get_attachment_metadata( $attachment_id );
+        $image_attr = wp_get_attachment_image_attr( $attachment_id, 'all', $image_attr_args );
 
-                        if ( is_array( $image_meta ) ) {
-                                $size_array = array( absint( $width ), absint( $height ) );
-                                $srcset     = wp_calculate_image_srcset( $size_array, $src, $image_meta, $attachment_id );
-                                $sizes      = wp_calculate_image_sizes( $size_array, $src, $image_meta, $attachment_id );
+        // If the image attribute fetch failed, return an empty string.
+        if ( empty( $image_attr ) ) {
+                return $html;
+        }
 
-                                if ( $srcset && ( $sizes || ! empty( $attr['sizes'] ) ) ) {
-                                        $attr['srcset'] = $srcset;
+        $hwstring     = image_hwstring( $image_attr['width'], $image_attr['height'] );
+        $attachment   = get_post( $attachment_id );
+        $default_attr = array(
+                'src'   => $image_attr['src'],
+                'class' => $image_attr['class'],
+                'alt'   => trim( strip_tags( $image_attr['alt'] ) ),
+        );
 
-                                        if ( empty( $attr['sizes'] ) ) {
-                                                $attr['sizes'] = $sizes;
-                                        }
-                                }
-                        }
-                }
+        $attr = wp_parse_args( $attr, $default_attr );
 
-                /**
-                 * Filters the list of attachment image attributes.
-                 *
-                 * @since 2.8.0
-                 *
-                 * @param array        $attr       Attributes for the image markup.
-                 * @param WP_Post      $attachment Image attachment post.
-                 * @param string|array $size       Requested size. Image size or array of width and height values
-                 *                                 (in that order). Default 'thumbnail'.
-                 */
-                $attr = apply_filters( 'wp_get_attachment_image_attributes', $attr, $attachment, $size );
-                $attr = array_map( 'esc_attr', $attr );
-                $html = rtrim( "<img $hwstring" );
-                foreach ( $attr as $name => $value ) {
-                        $html .= " $name=" . '"' . $value . '"';
+        // Generate 'srcset' and 'sizes' if not already present.
+        if ( empty( $attr['srcset'] ) &&
+                ! empty( $image_attr['srcset'] ) &&
+                ( ! empty( $image_attr['sizes'] ) || ! empty( $attr['sizes'] ) ) ) {
+
+                $attr['srcset'] = $image_attr['srcset'];
+
+                if ( empty( $attr['sizes'] ) ) {
+                        $attr['sizes'] = $image_attr['sizes'];
                 }
-                $html .= ' />';
         }
 
+        /**
+         * Filters the list of attachment image attributes.
+         *
+         * @since 2.8.0
+         *
+         * @param array        $attr       Attributes for the image markup.
+         * @param WP_Post      $attachment Image attachment post.
+         * @param string|array $size       Requested size. Image size or array of width and height values
+         *                                 (in that order). Default 'thumbnail'.
+         */
+        $attr = apply_filters( 'wp_get_attachment_image_attributes', $attr, $attachment, $size );
+        $attr = array_map( 'esc_attr', $attr );
+        $html = rtrim( "<img $hwstring" );
+
+        foreach ( $attr as $name => $value ) {
+                $html .= ' ' .  $name . '="' . $value . '"';
+        }
+
+        $html .= ' />';
+
         return $html;
 }
 

src/wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php

@@ -321 +321 @@
                 }
 
                 if ( in_array( 'alt_text', $fields, true ) ) {
-                        $data['alt_text'] = get_post_meta( $post->ID, '_wp_attachment_image_alt', true );
+                        $data['alt_text'] = wp_get_attachment_image_attr( $post->ID, 'alt' );
                 }
 
                 if ( in_array( 'media_type', $fields, true ) ) {

src/wp-includes/theme.php

@@ -1297 +1297 @@
                 $header_images[ $header_index ]['attachment_id']     = $header->ID;
                 $header_images[ $header_index ]['url']               = $url;
                 $header_images[ $header_index ]['thumbnail_url']     = $url;
-                $header_images[ $header_index ]['alt_text']          = get_post_meta( $header->ID, '_wp_attachment_image_alt', true );
+                $header_images[ $header_index ]['alt_text']          = wp_get_attachment_image_attr( $header->ID, 'alt' );
                 $header_images[ $header_index ]['attachment_parent'] = isset( $header_data['attachment_parent'] ) ? $header_data['attachment_parent'] : '';
 
                 if ( isset( $header_data['width'] ) ) {

tests/qunit/fixtures/wp-api-generated.js

@@ -5565 +5565 @@
         "caption": {
             "rendered": "<p>A sample caption</p>\n"
         },
-        "alt_text": "",
+        "alt_text": null,
         "media_type": "image",
         "mime_type": "image/jpeg",
         "media_details": {},
@@ -5626 +5626 @@
     "caption": {
         "rendered": "<p>A sample caption</p>\n"
     },
-    "alt_text": "",
+    "alt_text": null,
     "media_type": "image",
     "mime_type": "image/jpeg",
     "media_details": {},