image_get_intermediate_size( int $post_id, string|int[] $size = 'thumbnail' ): array|false

Description

Compatibility

Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.

Parameters

$post_idint

Attachment ID.

$sizestring|int[]optional

Image size. Accepts any registered image size name, or an array of width and height values in pixels (in that order). Default 'thumbnail'.Default: 'thumbnail'

Return value

array|false

Array of file relative path, width, and height on success. Additionally includes absolute path and URL if registered size is passed to $size parameter. False on failure.

• $filestring

  Filename of image.

• $widthint

  Width of image in pixels.

• $heightint

  Height of image in pixels.

• $pathstring

  Path of image relative to uploads directory.

• $urlstring

  URL of image.

Performance profile

How much work a call to image_get_intermediate_size() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.

Cost class

Heavy

Reaches the database via get_post().

Scaling

Scales with input

The body loops, so the work grows with what you pass in.

Instructions

8–129

Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 201.

Plugin surface

1 hook

Third-party callbacks on 'image_get_intermediate_size' run inside this call, and their cost is not bounded by anything here.

Called by

3

3 places in core call this, so the cost is paid more often than your own code shows.

What it touches

• hookthird-party callbacksapply_filters()called directly
• querycontent queryget_post()one call below image_get_intermediate_size()
• optionoption read or writeget_option()one call below image_get_intermediate_size()

Further down the call graph this can also reach cache, serialize and transient. Those are the worst case, several calls deep and usually down an error path, not what a normal call pays.

What one call costs · 12 distinct outcomes

One number would be a lie: the work depends on which branch runs. These are every distinct cost image_get_intermediate_size() can have, taken from its control-flow graph on PHP 8.5.

Hooks and filters fired · 1

One hook fires while image_get_intermediate_size() runs, in this order:

1. 1
   apply_filters( image_get_intermediate_size )filterline 873 (+93 into the body)

   Filters the output of image_get_intermediate_size()

Uses · 6

• wp_get_attachment_metadata()Retrieves attachment metadata for attachment ID.
• wp_image_matches_ratio()Helper function to test if aspect ratios for two images match.
• image_constrain_size_for_editor()Scales down the default size of an image.
• wp_get_attachment_url()Retrieves the URL for an attachment.
• path_join()Joins two filesystem paths together.
• apply_filters()Calls the callback functions that have been added to a filter hook.

Used by · 3

• _load_image_to_edit_path()Retrieves the path or URL of an attachment's attached file.
• image_downsize()Scales an image to fit a particular size (such as 'thumb' or 'medium').
• wp_image_editor()Loads the WP image-editing interface.

Source code

View on Trac ↗View on GitHub ↗

780function image_get_intermediate_size( $post_id, $size = 'thumbnail' ) {781	$imagedata = wp_get_attachment_metadata( $post_id );782 783	if ( ! $size || ! is_array( $imagedata ) || empty( $imagedata['sizes'] ) ) {784		return false;785	}786 787	$data = array();788 789	// Find the best match when '$size' is an array.790	if ( is_array( $size ) ) {791		$candidates = array();792 793		if ( ! isset( $imagedata['file'] ) && isset( $imagedata['sizes']['full'] ) ) {794			$imagedata['height'] = $imagedata['sizes']['full']['height'];795			$imagedata['width']  = $imagedata['sizes']['full']['width'];796		}797 798		foreach ( $imagedata['sizes'] as $_size => $data ) {799			// If there's an exact match to an existing image size, short circuit.800			if ( (int) $data['width'] === (int) $size[0] && (int) $data['height'] === (int) $size[1] ) {801				$candidates[ $data['width'] * $data['height'] ] = $data;802				break;803			}804 805			// If it's not an exact match, consider larger sizes with the same aspect ratio.806			if ( $data['width'] >= $size[0] && $data['height'] >= $size[1] ) {807				// If '0' is passed to either size, we test ratios against the original file.808				if ( 0 === $size[0] || 0 === $size[1] ) {809					$same_ratio = wp_image_matches_ratio( $data['width'], $data['height'], $imagedata['width'], $imagedata['height'] );810				} else {811					$same_ratio = wp_image_matches_ratio( $data['width'], $data['height'], $size[0], $size[1] );812				}813 814				if ( $same_ratio ) {815					$candidates[ $data['width'] * $data['height'] ] = $data;816				}817			}818		}819 820		if ( ! empty( $candidates ) ) {821			// Sort the array by size if we have more than one candidate.822			if ( 1 < count( $candidates ) ) {823				ksort( $candidates );824			}825 826			$data = array_shift( $candidates );827		} elseif ( ! empty( $imagedata['sizes']['thumbnail'] )828			&& $size[0] <= $imagedata['sizes']['thumbnail']['width']829			&& $size[1] <= $imagedata['sizes']['thumbnail']['width']830		) {831			/*832			 * When the size requested is smaller than the thumbnail dimensions, we833			 * fall back to the thumbnail size to maintain backward compatibility with834			 * pre-4.6 versions of WordPress.835			 */836			$data = $imagedata['sizes']['thumbnail'];837		} else {838			return false;839		}840 841		// Constrain the width and height attributes to the requested values.842		list( $data['width'], $data['height'] ) = image_constrain_size_for_editor( $data['width'], $data['height'], $size );843 844	} elseif ( ! empty( $imagedata['sizes'][ $size ] ) ) {845		$data = $imagedata['sizes'][ $size ];846	}847 848	// If we still don't have a match at this point, return false.849	if ( empty( $data ) ) {850		return false;851	}852 853	// Include the full filesystem path of the intermediate file.854	if ( empty( $data['path'] ) && ! empty( $data['file'] ) && ! empty( $imagedata['file'] ) ) {855		$file_url     = wp_get_attachment_url( $post_id );856		$data['path'] = path_join( dirname( $imagedata['file'] ), $data['file'] );857		$data['url']  = path_join( dirname( $file_url ), $data['file'] );858	}859

Changelog

Introduced in 2.5.0. Unchanged from 6.7.7 through 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data

Generated from the wordpress-develop 6.9.7 tag, from src/wp-includes/media.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.

Corrections

Something wrong on this page? Report it and it gets fixed in the next regeneration.