| | 856 | /** |
| | 857 | * Retrieve an image attribute value. |
| | 858 | * |
| | 859 | * Retrieve either a single image attribute value or all relevant attribute values. The possible |
| | 860 | * values are `alt`, `description`, `caption`, `src`, `width`, `height`, `srcset`, `sizes`, `class`. When |
| | 861 | * retrieving src, width, height, srcset, sizes, or class, you can specify the size of the image to retrieve |
| | 862 | * in the args parameter. Passing in an empty attribute value will return all relevant values. |
| | 863 | * |
| | 864 | * @since 5.X |
| | 865 | * |
| | 866 | * @param int $attachment_id Image attachment ID. |
| | 867 | * @param string|array $attribute Image attribute to retrieve. |
| | 868 | * @param array $args Optional. Array of attributes for the function. Currently only |
| | 869 | * supports 'size' for the image source. |
| | 870 | * @return string|array Returns the value of the attribute or attributes requested. A single |
| | 871 | * attribute will return a single value. An array of attributes or no |
| | 872 | * attribute will return an array of values. |
| | 873 | */ |
| | 874 | function wp_get_attachment_image_attr( $attachment_id, $attribute = [], $args = [] ) { |
| | 875 | $image = get_post( $attachment_id ); |
| | 876 | |
| | 877 | // If this isn't an image, bail early with null. |
| | 878 | if ( empty( $image ) ) { |
| | 879 | return null; |
| | 880 | } |
| | 881 | |
| | 882 | $values = []; |
| | 883 | $names = []; |
| | 884 | |
| | 885 | if ( empty( $attribute ) ) { |
| | 886 | // If an empty value is passed for the attr name, return all our attributes. |
| | 887 | $names = array( |
| | 888 | 'alt', |
| | 889 | 'description', |
| | 890 | 'caption', |
| | 891 | 'src', |
| | 892 | 'width', |
| | 893 | 'height', |
| | 894 | 'srcset', |
| | 895 | 'sizes', |
| | 896 | 'class', |
| | 897 | ); |
| | 898 | } elseif ( is_string( $attribute ) ) { |
| | 899 | // If the attribute name is a string, convert it to an array. |
| | 900 | $names = array( $attribute ); |
| | 901 | } |
| | 902 | |
| | 903 | // Get a valid args array. |
| | 904 | $default_args = array( |
| | 905 | 'size' => null, |
| | 906 | ); |
| | 907 | |
| | 908 | $args = wp_parse_args( $args, $default_args ); |
| | 909 | |
| | 910 | // Loop through our names and get the value for each one. |
| | 911 | foreach ( $names as $name ) { |
| | 912 | switch ( $name ) { |
| | 913 | case 'alt': |
| | 914 | $values[ $name ] = get_post_meta( $attachment_id, '_wp_attachment_image_alt', true ); |
| | 915 | break; |
| | 916 | |
| | 917 | case 'description': |
| | 918 | $values[ $name ] = $image->post_content; |
| | 919 | break; |
| | 920 | |
| | 921 | case 'caption': |
| | 922 | $values[ $name ] = $image->post_excerpt; |
| | 923 | break; |
| | 924 | |
| | 925 | case 'src': |
| | 926 | if ( ! isset( $image_src ) ) { |
| | 927 | $image_src = image_downsize( $attachment_id, $args['size'] ); |
| | 928 | } |
| | 929 | |
| | 930 | $values[ $name ] = $image_src[0]; |
| | 931 | break; |
| | 932 | |
| | 933 | case 'width': |
| | 934 | if ( ! isset( $image_src ) ) { |
| | 935 | $image_src = image_downsize( $attachment_id, $args['size'] ); |
| | 936 | } |
| | 937 | |
| | 938 | $values[ $name ] = $image_src[1]; |
| | 939 | break; |
| | 940 | |
| | 941 | case 'height': |
| | 942 | if ( ! isset( $image_src ) ) { |
| | 943 | $image_src = image_downsize( $attachment_id, $args['size'] ); |
| | 944 | } |
| | 945 | |
| | 946 | $values[ $name ] = $image_src[2]; |
| | 947 | break; |
| | 948 | |
| | 949 | case 'srcset': |
| | 950 | $values[ $name ] = wp_get_attachment_image_srcset( $attachment_id, $args['size'] ); |
| | 951 | break; |
| | 952 | |
| | 953 | case 'sizes': |
| | 954 | $values[ $name ] = wp_get_attachment_image_sizes( $attachment_id, $args['size'] ); |
| | 955 | break; |
| | 956 | |
| | 957 | case 'class': |
| | 958 | $size_class = $args['size']; |
| | 959 | |
| | 960 | if ( is_array( $size_class ) ) { |
| | 961 | $size_class = join( 'x', $size_class ); |
| | 962 | } |
| | 963 | |
| | 964 | $values[ $name ] = 'attachment-' . $size_class . ' size-' . $size_class; |
| | 965 | break; |
| | 966 | } |
| | 967 | } |
| | 968 | |
| | 969 | /** |
| | 970 | * Filters the image attr result. |
| | 971 | * |
| | 972 | * Will apply to all image attribute types. |
| | 973 | * |
| | 974 | * @since 5.x |
| | 975 | * |
| | 976 | * @param string|int $values Value of the attribute. |
| | 977 | * @param int $attachment_id Image attachment ID. |
| | 978 | * @param string $name Name of the attribute being retrieved. |
| | 979 | * @param array $args Arguments passed into the function. |
| | 980 | */ |
| | 981 | $values = apply_filters( 'wp_get_attachment_image_attr', $values, $attachment_id, $attribute, $args ); |
| | 982 | |
| | 983 | // If we didn't request a single attribute, we're done. |
| | 984 | if ( is_array( $attribute ) || empty( $attribute ) ) { |
| | 985 | return $values; |
| | 986 | } |
| | 987 | |
| | 988 | if ( ! empty( $values[ $attribute ] ) ) { |
| | 989 | $value = $values[ $attribute ]; |
| | 990 | } else { |
| | 991 | $value = null; |
| | 992 | } |
| | 993 | |
| | 994 | /** |
| | 995 | * Filters the image attr result. |
| | 996 | * |
| | 997 | * This is a dynamic filter that will generate a distinct filter for each attribute type. |
| | 998 | * It only runs if the requested attribute is a string. |
| | 999 | * |
| | 1000 | * <code> |
| | 1001 | * <?php |
| | 1002 | * function filter_alt_text( $alt ) { |
| | 1003 | * $alt = $alt + ' Extra content'; |
| | 1004 | * return $alt; |
| | 1005 | * } |
| | 1006 | * add_filter( 'wp_get_attachment_image_attr_alt', 'filter_alt_text' ); |
| | 1007 | * </code> |
| | 1008 | * |
| | 1009 | * @since 5.x |
| | 1010 | * |
| | 1011 | * @param string|int $value Value of the attribute. |
| | 1012 | * @param int $attachment_id Image attachment ID. |
| | 1013 | * @param array $args Arguments passed into the function. |
| | 1014 | */ |
| | 1015 | $value = apply_filters( 'wp_get_attachment_image_attr_' . $attribute, $value, $attachment_id, $args ); |
| | 1016 | |
| | 1017 | return $value; |
| | 1018 | } |
| | 1019 | |