image_downsize()WP 2.5.0

Scale an image to fit a particular size (such as 'thumb' or 'medium').

The URL might be the original image, or it might be a resized version. This function won't create a new resized copy, it will just return an already resized one if it exists.

A plugin may use the image_downsize filter to hook into and offer image resizing services for images. The hook must return an array with the same elements that are normally returned from the function.

1 time — 0.001024 sec (very slow) | 50000 times — 6.16 sec (fast) | PHP 7.0.8, WP 4.6
Hooks from the function

Return

Array|false. Array of image data, or boolean false if no image is available.

Usage

image_downsize( $id, $size );
$id(int) (required)
Attachment ID for image.
$size(string|int[])
Image size. Accepts any registered image size name, or an array of width and height values in pixels (in that order).
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.4.3

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;
}