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.   
  5. // Current width of the image. 
  6. $current_width = -1; 
  7.   
  8. // Current height of the image. 
  9. $current_height = -1; 
  10.   
  11. // Optional. Max width in pixels to constrain to. Default 0. 
  12. $max_width = -1; 
  13.   
  14. // Optional. Max height in pixels to constrain to. Default 0. 
  15. $max_height = -1; 
  16.   
  17. // NOTICE! Understand what this does before running. 
  18. $result = wp_constrain_dimensions($current_width, $current_height, $max_width, $max_height); 
  19.     

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