image_downsize() WordPress Function

The image_downsize() function is used to downsize an image to fit within a specified width and height. This is useful for creating thumbnails or for limiting the size of an image in order to reduce page load times. The function accepts an array of parameters, including the desired width and height, as well as a "crop" parameter which, when set to true, will crop the image to fit within the specified width and height.

image_downsize( int $id, string|int[] $size = 'medium' ) #

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


Description

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.


Top ↑

Parameters

$id

(int)(Required)Attachment ID for image.

$size

(string|int[])(Optional) Image size. Accepts any registered image size name, or an array of width and height values in pixels (in that order).

Default value: 'medium'


Top ↑

Return

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

  • (string) Image source URL.
  • '1'
    (int) Image width in pixels.
  • '2'
    (int) Image height in pixels.
  • '3'
    (bool) Whether the image is a resized image.


Top ↑

Source

File: 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 ) {
		// Fall back to the old thumbnail.
		$thumb_file = wp_get_attachment_thumb_file( $id );
		$info       = null;

		if ( $thumb_file ) {
			$info = wp_getimagesize( $thumb_file );
		}

		if ( $thumb_file && $info ) {
			$img_url         = str_replace( $img_url_basename, wp_basename( $thumb_file ), $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;
}


Top ↑

Changelog

Changelog
VersionDescription
2.5.0Introduced.

The content displayed on this page has been created in part by processing WordPress source code files which are made available under the GPLv2 (or a later version) license by theĀ Free Software Foundation. In addition to this, the content includes user-written examples and information. All material is subject to review and curation by the WPPaste.com community.

Show More
Show More