image_resize_dimensions( int $orig_w, int $orig_h, int $dest_w, int $dest_h, bool|array $crop = false ): 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

$orig_wint

Original width in pixels.

$orig_hint

Original height in pixels.

$dest_wint

New width in pixels.

$dest_hint

New height in pixels.

$cropbool|arrayoptional

Image cropping behavior. If false, the image will be scaled (default). If true, image will be cropped to the specified dimensions using center positions. If an array, the image will be cropped using the array to specify the crop location: @type string $0 The x crop position. Accepts 'left', 'center', or 'right'.Default: false

• $1string

  The y crop position. Accepts 'top', 'center', or 'bottom'.

Return value

array|false

Returned array matches parameters for imagecopyresampled(). False on failure.

Performance profile

How much work a call to image_resize_dimensions() 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

Trivial

Touches nothing outside its own arguments.

Scaling

Constant

No loop in the body: the same number of instructions runs whatever you pass in.

Instructions

8–124

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

Plugin surface

2 hooks

Third-party callbacks on 'image_resize_dimensions', 'wp_image_resize_identical_dimensions' 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

What one call costs · 32 distinct outcomes

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

Hooks and filters fired · 2

2 hooks fire while image_resize_dimensions() runs, in this order:

1. 1
   apply_filters( image_resize_dimensions )filterline 569 (+26 into the body)

   Filters whether to preempt calculating the image resize dimensions.

2. 2
   apply_filters( wp_image_resize_identical_dimensions )filterline 661 (+118 into the body)

   Filters whether to proceed with making an image sub-size with identical dimensions with the original/source image. Differences of 1px may be due to rounding and are ignored.

Uses · 3

• apply_filters()Calls the callback functions that have been added to a filter hook.
• wp_constrain_dimensions()Calculates the new dimensions for a down-sampled image.
• wp_fuzzy_number_match()Checks if two numbers are nearly the same.

Used by · 3

• WP_Image_Editor_GD::_resize()
• WP_Image_Editor_Imagick::resize()Resizes current image.
• wp_get_missing_image_subsizes()Compare the existing image sub-sizes (as saved in the attachment meta) to the currently registered image sub-sizes, and return the difference.

Source code

View on Trac ↗View on GitHub ↗

543function image_resize_dimensions( $orig_w, $orig_h, $dest_w, $dest_h, $crop = false ) {544 545	if ( $orig_w <= 0 || $orig_h <= 0 ) {546		return false;547	}548	// At least one of $dest_w or $dest_h must be specific.549	if ( $dest_w <= 0 && $dest_h <= 0 ) {550		return false;551	}552 553	/**554	 * Filters whether to preempt calculating the image resize dimensions.555	 *556	 * Returning a non-null value from the filter will effectively short-circuit557	 * image_resize_dimensions(), returning that value instead.558	 *559	 * @since 3.4.0560	 *561	 * @param null|mixed $null   Whether to preempt output of the resize dimensions.562	 * @param int        $orig_w Original width in pixels.563	 * @param int        $orig_h Original height in pixels.564	 * @param int        $dest_w New width in pixels.565	 * @param int        $dest_h New height in pixels.566	 * @param bool|array $crop   Whether to crop image to specified width and height or resize.567	 *                           An array can specify positioning of the crop area. Default false.568	 */569	$output = apply_filters( 'image_resize_dimensions', null, $orig_w, $orig_h, $dest_w, $dest_h, $crop );570 571	if ( null !== $output ) {572		return $output;573	}574 575	// Stop if the destination size is larger than the original image dimensions.576	if ( empty( $dest_h ) ) {577		if ( $orig_w < $dest_w ) {578			return false;579		}580	} elseif ( empty( $dest_w ) ) {581		if ( $orig_h < $dest_h ) {582			return false;583		}584	} else {585		if ( $orig_w < $dest_w && $orig_h < $dest_h ) {586			return false;587		}588	}589 590	if ( $crop ) {591		/*592		 * Crop the largest possible portion of the original image that we can size to $dest_w x $dest_h.593		 * Note that the requested crop dimensions are used as a maximum bounding box for the original image.594		 * If the original image's width or height is less than the requested width or height595		 * only the greater one will be cropped.596		 * For example when the original image is 600x300, and the requested crop dimensions are 400x400,597		 * the resulting image will be 400x300.598		 */599		$aspect_ratio = $orig_w / $orig_h;600		$new_w        = min( $dest_w, $orig_w );601		$new_h        = min( $dest_h, $orig_h );602 603		if ( ! $new_w ) {604			$new_w = (int) round( $new_h * $aspect_ratio );605		}606 607		if ( ! $new_h ) {608			$new_h = (int) round( $new_w / $aspect_ratio );609		}610 611		$size_ratio = max( $new_w / $orig_w, $new_h / $orig_h );612 613		$crop_w = round( $new_w / $size_ratio );614		$crop_h = round( $new_h / $size_ratio );615 616		if ( ! is_array( $crop ) || count( $crop ) !== 2 ) {617			$crop = array( 'center', 'center' );618		}619 620		list( $x, $y ) = $crop;621 622		if ( 'left' === $x ) {

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.8.8 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.