image_downsize() │ WP 2.5.0

Gets an array of image data for the specified size: URL, width and height of the attachment image.

This function is the core for wp_get_attachment_image_src(). Only it cannot be passed the third parameter $icon. It retrieves the URL and dimensions of the attachment that is an image.

Retrieves the URL of the original image or its reduced copy. The function does not create a reduced copy of the image, but only gets the URL of an already reduced image that best fits the specified dimensions. If arbitrary dimensions are specified in an array, it selects an appropriate image and proportional dimensions. See examples.

Uses: wp_get_attachment_url(), image_get_intermediate_size()
Used By: wp_get_attachment_thumb_url(), wp_get_attachment_image_src()
1 time — 0.001024 sec (very slow) | 50000 times — 6.16 sec (fast) | PHP 7.0.8, WP 4.6
Hooks from the function

Returns

Array|false. Array with image data or false if it failed to get the image.

The array is returned in the following format:

array(
	[0] => url     // URL of the image
	[1] => width   // width of the image
	[2] => height  // height of the image
	[3] => true    // true if the URL of a reduced copy was obtained, not the original
)

Usage

image_downsize( $id, $size );
$id(int) (required)
ID of the attachment image whose data is to be retrieved.
$size(string)

The size of the image whose data to retrieve. The URL will differ. In this parameter you can specify sizes registered in WP, by default these are:

  • thumbnail — thumbnail (usually 150x150) cropped.
  • medium — medium size, not cropped. (Default).
  • large — large size, not cropped.
  • full — Original image. If a «scaled» image is created, that will be returned.

array( 32, 32 ) — you can also specify the size as an array of two values (width, height). In this case the most appropriate size from existing ones will be selected, then the image will be shrunk/stretched to the specified dimensions.

Since version 2.5. this parameter does not affect the size of media icons (icons for files), they are always shown at the original size.

Default: 'medium'

Examples

0

#1 Get image URL of medium size

Let's write a similar to wp_get_attachment_thumb_url() function that will get the medium size of the attachment image, but not thumbnail size.

$id is the ID of the attachment.

function wp_get_attachment_medium_url( $id ){

	$medium_array = image_downsize( $id, 'medium' );
	$medium_path = $medium_array[0];

	return $medium_path;
}
0

#2 How the function works

Suppose we have an attachment with ID 55 - it's a picture: http://example.com/wp-content/uploads/2014/02/wix.png with a size of 500x258 pixels. In the settings of media files we have the following sizes for images: 80x80, 300x300, 1000x1000. So, when loading this image, WP created two smaller copies: 80x80, 300x300.

Now see what the function will get when you specify different sizes:

$img = image_downsize( 55, 'full' );
/*
Array
(
	[0] => http://example.com/wp-content/uploads/2014/02/wix.png
	[1] => 500
	[2] => 258
	[3] =>
)
*/

$img = image_downsize( 55, 'thumbnail' );
/*
Array
(
	[0] => http://example.com/wp-content/uploads/2014/02/wix-80x80.png
	[1] => 80
	[2] => 80
	[3] => 1
)
*/

$img = image_downsize( 55 );
/*
Array
(
	[0] => http://example.com/wp-content/uploads/2014/02/wix-300x258.png
	[1] => 300
	[2] => 258
	[3] => 1
)
*/

$img = image_downsize( 55, array(100, 90) );
/*
Array
(
	[0] => http://example.com/wp-content/uploads/2014/02/wix.png
	[1] => 100
	[2] => 51
	[3] =>
)
*/

$img = image_downsize( 55, array(100, 80) );
/*
Array
(
	[0] => http://example.com/wp-content/uploads/2014/02/wix-80x80.png
	[1] => 80
	[2] => 80
	[3] => 1
)
*/

Changelog

Since 2.5.0 Introduced.

image_downsize() code WP 6.9.1

wp-includes/media.php 
function image_downsize( $id, $size = 'medium' ) {
	$is_image = wp_attachment_is_image( $id );

	/**
	 * Filters whether to preempt the output of image_downsize().
	 *
	 * Returning a truthy value from the filter will effectively short-circuit
	 * down-sizing the image, returning that value instead.
	 *
	 * @since 2.5.0
	 *
	 * @param bool|array   $downsize Whether to short-circuit the image downsize.
	 * @param int          $id       Attachment ID for image.
	 * @param string|int[] $size     Requested image size. Can be any registered image size name, or
	 *                               an array of width and height values in pixels (in that order).
	 */
	$out = apply_filters( 'image_downsize', false, $id, $size );

	if ( $out ) {
		return $out;
	}

	$img_url          = wp_get_attachment_url( $id );
	$meta             = wp_get_attachment_metadata( $id );
	$width            = 0;
	$height           = 0;
	$is_intermediate  = false;
	$img_url_basename = wp_basename( $img_url );

	/*
	 * If the file isn't an image, attempt to replace its URL with a rendered image from its meta.
	 * Otherwise, a non-image type could be returned.
	 */
	if ( ! $is_image ) {
		if ( ! empty( $meta['sizes']['full'] ) ) {
			$img_url          = str_replace( $img_url_basename, $meta['sizes']['full']['file'], $img_url );
			$img_url_basename = $meta['sizes']['full']['file'];
			$width            = $meta['sizes']['full']['width'];
			$height           = $meta['sizes']['full']['height'];
		} else {
			return false;
		}
	}

	// Try for a new style intermediate size.
	$intermediate = image_get_intermediate_size( $id, $size );

	if ( $intermediate ) {
		$img_url         = str_replace( $img_url_basename, $intermediate['file'], $img_url );
		$width           = $intermediate['width'];
		$height          = $intermediate['height'];
		$is_intermediate = true;
	} elseif ( 'thumbnail' === $size && ! empty( $meta['thumb'] ) && is_string( $meta['thumb'] ) ) {
		// Fall back to the old thumbnail.
		$imagefile = get_attached_file( $id );
		$thumbfile = str_replace( wp_basename( $imagefile ), wp_basename( $meta['thumb'] ), $imagefile );

		if ( file_exists( $thumbfile ) ) {
			$info = wp_getimagesize( $thumbfile );

			if ( $info ) {
				$img_url         = str_replace( $img_url_basename, wp_basename( $thumbfile ), $img_url );
				$width           = $info[0];
				$height          = $info[1];
				$is_intermediate = true;
			}
		}
	}

	if ( ! $width && ! $height && isset( $meta['width'], $meta['height'] ) ) {
		// Any other type: use the real image.
		$width  = $meta['width'];
		$height = $meta['height'];
	}

	if ( $img_url ) {
		// We have the actual image size, but might need to further constrain it if content_width is narrower.
		list( $width, $height ) = image_constrain_size_for_editor( $width, $height, $size );

		return array( $img_url, $width, $height, $is_intermediate );
	}

	return false;
}

Thumbnail (images)

Images