wp_constrain_dimensions

Calculates the new dimensions for a down-sampled image.

Description

(array) wp_constrain_dimensions( (int) $current_width, (int) $current_height, (int) $max_width = 0, (int) $max_height = 0 ); 

If either width or height are empty, no constraint is applied on that dimension.

Returns (array)

First item is the width, the second item is the height.

Parameters (4)

0. $current_width (int)
Current width of the image.
1. $current_height (int)
Current height of the image.
2. $max_width — Optional. (int)
Max width in pixels to constrain to. Default 0.
3. $max_height — Optional. (int)
Max height in pixels to constrain to. Default 0.

Usage

  1. if ( !function_exists( 'wp_constrain_dimensions' ) ) { 
  2. require_once ABSPATH . WPINC . '/media.php'; 
  3.  
  4. // Current width of the image. 
  5. $current_width = -1; 
  6.  
  7. // Current height of the image. 
  8. $current_height = -1; 
  9.  
  10. // Optional. Max width in pixels to constrain to. Default 0. 
  11. $max_width = -1; 
  12.  
  13. // Optional. Max height in pixels to constrain to. Default 0. 
  14. $max_height = -1; 
  15.  
  16. // NOTICE! Understand what this does before running. 
  17. $result = wp_constrain_dimensions($current_width, $current_height, $max_width, $max_height); 
  18.  

Defined (1)

The function is defined in the following location(s).

/wp-includes/media.php  
  1. function wp_constrain_dimensions( $current_width, $current_height, $max_width = 0, $max_height = 0 ) { 
  2. if ( !$max_width && !$max_height ) 
  3. return array( $current_width, $current_height ); 
  4.  
  5. $width_ratio = $height_ratio = 1.0; 
  6. $did_width = $did_height = false; 
  7.  
  8. if ( $max_width > 0 && $current_width > 0 && $current_width > $max_width ) { 
  9. $width_ratio = $max_width / $current_width; 
  10. $did_width = true; 
  11.  
  12. if ( $max_height > 0 && $current_height > 0 && $current_height > $max_height ) { 
  13. $height_ratio = $max_height / $current_height; 
  14. $did_height = true; 
  15.  
  16. // Calculate the larger/smaller ratios 
  17. $smaller_ratio = min( $width_ratio, $height_ratio ); 
  18. $larger_ratio = max( $width_ratio, $height_ratio ); 
  19.  
  20. if ( (int) round( $current_width * $larger_ratio ) > $max_width || (int) round( $current_height * $larger_ratio ) > $max_height ) { 
  21. // The larger ratio is too big. It would result in an overflow. 
  22. $ratio = $smaller_ratio; 
  23. } else { 
  24. // The larger ratio fits, and is likely to be a more "snug" fit. 
  25. $ratio = $larger_ratio; 
  26.  
  27. // Very small dimensions may result in 0, 1 should be the minimum. 
  28. $w = max ( 1, (int) round( $current_width * $ratio ) ); 
  29. $h = max ( 1, (int) round( $current_height * $ratio ) ); 
  30.  
  31. // Sometimes, due to rounding, we'll end up with a result like this: 465x700 in a 177x177 box is 117x176... a pixel short 
  32. // 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. 
  33. // Thus we look for dimensions that are one pixel shy of the max value and bump them up 
  34.  
  35. // Note: $did_width means it is possible $smaller_ratio == $width_ratio. 
  36. if ( $did_width && $w == $max_width - 1 ) { 
  37. $w = $max_width; // Round it up 
  38.  
  39. // Note: $did_height means it is possible $smaller_ratio == $height_ratio. 
  40. if ( $did_height && $h == $max_height - 1 ) { 
  41. $h = $max_height; // Round it up 
  42.  
  43. /** 
  44. * Filters dimensions to constrain down-sampled images to. 
  45. * @since 4.1.0 
  46. * @param array $dimensions The image width and height. 
  47. * @param int $current_width The current width of the image. 
  48. * @param int $current_height The current height of the image. 
  49. * @param int $max_width The maximum width permitted. 
  50. * @param int $max_height The maximum height permitted. 
  51. */ 
  52. return apply_filters( 'wp_constrain_dimensions', array( $w, $h ), $current_width, $current_height, $max_width, $max_height );