wp_constrain_dimensions( int $current_width, int $current_height, int $max_width = 0, int $max_height = 0 ): int[]
- Since
- 2.5.0
- Source
wp-includes/media.php:443
Description
If either width or height are empty, no constraint is applied on that dimension.
Compatibility
- WordPress
- since 2.5.0
- PHP
- 7.4–8.6-dev
- 6.7.7
- 6.8.8
- 6.9.7
- 7.0.4
- 7.1.0
Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.
Parameters
$current_widthint- Current width of the image.
$current_heightint- Current height of the image.
$max_widthintoptional- Max width in pixels to constrain to. Default 0.Default:
0 $max_heightintoptional- Max height in pixels to constrain to. Default 0.Default:
0
Return value
int[]- An array of width and height values.
$0intThe width in pixels.$1intThe height in pixels.
Performance profile
How much work a call to wp_constrain_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
- Scaling
- Constant
- Instructions
- 9–77
- Plugin surface
- 1 hook
- Called by
- 7
Touches nothing outside its own arguments.
No loop in the body: the same number of instructions runs whatever you pass in.
Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 81.
Third-party callbacks on 'wp_constrain_dimensions' run inside this call, and their cost is not bounded by anything here.
7 places in core call this, so the cost is paid more often than your own code shows.
What it touches
- hookthird-party callbacks
apply_filters()called directly
What one call costs · 3 distinct outcomes
One number would be a lie: the work depends on which branch runs. These are every distinct cost wp_constrain_dimensions() can have, taken from its control-flow graph on PHP 8.5.
| When | Instructions | Calls it makes |
|---|---|---|
| always | 9 | none |
$max_width | 49–70 | round(), round(), round() |
!$max_width | 55–77 | round(), round(), round(), round() |
Across PHP versions
| PHP | Compiled | Executed | Branches | Notes |
|---|---|---|---|---|
| 8.6-dev | 81 | 9–77 | 14 | |
| 8.5 | 81 | 9–77 | 14 | |
| 8.4 | 81 | 9–77 | 14 | 16 fewer instructions than PHP 8.3 |
| 8.3 | 97 | 9–93 | 14 | |
| 8.2 | 97 | 9–93 | 14 | |
| 8.1 | 97 | 9–93 | 14 | |
| 7.4 | 97 | 9–93 | 14 |
An instruction is not a fixed amount of time, so a matching count is not necessarily the same speed; what it rules out is a difference in the work itself.
Hooks and filters fired · 1
One hook fires while wp_constrain_dimensions() runs, in this order:
- apply_filters( wp_constrain_dimensions )filterline 513 (+70 into the body)
Filters dimensions to constrain down-sampled images to.
Uses · 1
- apply_filters()Calls the callback functions that have been added to a filter hook.
Used by · 7
- get_udims()Calculated the new dimensions for a downsampled image.
- image_constrain_size_for_editor()Scales down the default size of an image.
- image_resize_dimensions()Retrieves calculated resize dimensions for use in WP_Image_Editor.
- wp_expand_dimensions()Based on a supplied width/height example, returns the biggest possible dimensions based on the max width/height.
- wp_image_editor()Loads the WP image-editing interface.
- wp_image_matches_ratio()Helper function to test if aspect ratios for two images match.
- wp_shrink_dimensions()Calculates the new dimensions for a downsampled image.
Source code
function wp_constrain_dimensions( $current_width, $current_height, $max_width = 0, $max_height = 0 ) { if ( ! $max_width && ! $max_height ) { return array( $current_width, $current_height ); } $width_ratio = 1.0; $height_ratio = 1.0; $did_width = false; $did_height = false; if ( $max_width > 0 && $current_width > 0 && $current_width > $max_width ) { $width_ratio = $max_width / $current_width; $did_width = true; } if ( $max_height > 0 && $current_height > 0 && $current_height > $max_height ) { $height_ratio = $max_height / $current_height; $did_height = true; } // Calculate the larger/smaller ratios. $smaller_ratio = min( $width_ratio, $height_ratio ); $larger_ratio = max( $width_ratio, $height_ratio ); if ( (int) round( $current_width * $larger_ratio ) > $max_width || (int) round( $current_height * $larger_ratio ) > $max_height ) { // The larger ratio is too big. It would result in an overflow. $ratio = $smaller_ratio; } else { // The larger ratio fits, and is likely to be a more "snug" fit. $ratio = $larger_ratio; } // Very small dimensions may result in 0, 1 should be the minimum. $w = max( 1, (int) round( $current_width * $ratio ) ); $h = max( 1, (int) round( $current_height * $ratio ) ); /* * Sometimes, due to rounding, we'll end up with a result like this: * 465x700 in a 177x177 box is 117x176... a pixel short. * We also have issues with recursive calls resulting in an ever-changing result. * Constraining to the result of a constraint should yield the original result. * Thus we look for dimensions that are one pixel shy of the max value and bump them up. */ // Note: $did_width means it is possible $smaller_ratio == $width_ratio. if ( $did_width && $w === $max_width - 1 ) { $w = $max_width; // Round it up. } // Note: $did_height means it is possible $smaller_ratio == $height_ratio. if ( $did_height && $h === $max_height - 1 ) { $h = $max_height; // Round it up. } /** * Filters dimensions to constrain down-sampled images to. * * @since 4.1.0 * * @param int[] $dimensions { * An array of width and height values. * * @type int $0 The width in pixels. * @type int $1 The height in pixels. * } * @param int $current_width The current width of the image. * @param int $current_height The current height of the image. * @param int $max_width The maximum width permitted. * @param int $max_height The maximum height permitted. */ return apply_filters( 'wp_constrain_dimensions', array( $w, $h ), $current_width, $current_height, $max_width, $max_height );}Changelog
Introduced in 2.5.0. Unchanged from 6.7.7 through 7.1.0.
Signature, return type and hooks compared across 5 parsed releases.
About this page
- Parsed data
- Generated from the wordpress-develop 6.7.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.