Ticket #30180: 30180.1.unit-tests.patch

src/wp-includes/media.php

@@ -854 +854 @@
 }
 
 /**
+ * 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.
+ * @param array        $args          Optional. Array of attributes for the function. Currently only
+ *                                    supports 'size' for the image source.
+ * @return 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 = [], $args = [] ) {
+        $image = get_post( $attachment_id );
+
+        // If this isn't an image, bail early with null.
+        if ( empty( $image ) ) {
+                return null;
+        }
+
+        $values = [];
+        $names  = [];
+
+        if ( empty( $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(
+                '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       = image_downsize( $attachment_id, $args['size'] );
+                                }
+
+                                $values[ $name ] = $image_src[0];
+                                break;
+
+                        case 'width':
+                                if ( ! isset( $image_src ) ) {
+                                        $image_src       = image_downsize( $attachment_id, $args['size'] );
+                                }
+
+                                $values[ $name ] = $image_src[1];
+                                break;
+
+                        case 'height':
+                                if ( ! isset( $image_src ) ) {
+                                        $image_src       = image_downsize( $attachment_id, $args['size'] );
+                                }
+
+                                $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 ) ) {
+                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

tests/phpunit/tests/media/getAttachmentAttributes.php

@@ +1 @@
+<?php
+
+/**
+ * @group media
+ * @group attribute
+ */
+class Tests_Media_GetAttachmentAttributes extends WP_UnitTestCase {
+        public function test_should_return_attachment_attr_alt() {
+                $alt = 'Alt text';
+
+                $a = self::factory()->attachment->create_object(
+                        [
+                                'post_title'     => 'Unit Test Attachment',
+                                'post_content'   => '',
+                        ]
+                );
+
+                $attachment = get_post( $a );
+
+                update_post_meta( $attachment->ID, '_wp_attachment_image_alt', $alt );
+
+                $found    = wp_get_attachment_image_attr( $attachment->ID, 'alt' );
+                $expected = $alt;
+
+                $this->assertSame( $expected, $found );
+        }
+
+        public function test_should_return_attachment_attr_caption() {
+                $caption = 'Image Caption';
+
+                $a = self::factory()->attachment->create_object(
+                        [
+                                'post_title'     => 'Unit Test Attachment',
+                                'post_content'   => '',
+                                'post_excerpt'   => $caption,
+                        ]
+                );
+
+                $attachment = get_post( $a );
+
+                $found    = wp_get_attachment_image_attr( $attachment->ID, 'caption' );
+                $expected = $caption;
+
+                $this->assertSame( $expected, $found );
+        }
+
+        public function test_should_return_attachment_attr_description() {
+                $description = 'Image Description';
+
+                $a = self::factory()->attachment->create_object(
+                        [
+                                'post_title'     => 'Unit Test Attachment',
+                                'post_content'   => $description,
+                        ]
+                );
+
+                $attachment = get_post( $a );
+
+                $found    = wp_get_attachment_image_attr( $attachment->ID, 'description' );
+                $expected = $description;
+
+                $this->assertSame( $expected, $found );
+        }
+
+        public function test_should_return_attachment_attr_class() {
+                $description = 'Image Description';
+
+                $a = self::factory()->attachment->create_object(
+                        [
+                                'post_title'     => 'Unit Test Attachment',
+                                'post_content'   => '',
+                        ]
+                );
+
+                $attachment = get_post( $a );
+
+                $found = wp_get_attachment_image_attr(
+                        $attachment->ID,
+                        'class',
+                        [ 'size' => 'large' ]
+                );
+
+                $expected = 'attachment-large size-large';
+
+                $this->assertSame( $expected, $found );
+        }
+}