From b5e754ee35f531ab889efd6ce74bfae48c65cccc Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Fri, 18 Aug 2023 17:56:17 +0000 Subject: [PATCH] Media: Standardise documentation of the `$crop` parameter for various media functions and methods. See #58833 Built from https://develop.svn.wordpress.org/trunk@56416 git-svn-id: http://core.svn.wordpress.org/trunk@55928 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-includes/class-wp-image-editor-gd.php | 18 +++++- wp-includes/class-wp-image-editor-imagick.php | 9 ++- wp-includes/class-wp-image-editor.php | 9 ++- wp-includes/media.php | 58 +++++++++++-------- wp-includes/version.php | 2 +- 5 files changed, 68 insertions(+), 28 deletions(-) diff --git a/wp-includes/class-wp-image-editor-gd.php b/wp-includes/class-wp-image-editor-gd.php index 5f88d209a6..2b168999aa 100644 --- a/wp-includes/class-wp-image-editor-gd.php +++ b/wp-includes/class-wp-image-editor-gd.php @@ -165,7 +165,14 @@ class WP_Image_Editor_GD extends WP_Image_Editor { * * @param int|null $max_w Image width. * @param int|null $max_h Image height. - * @param bool|array $crop + * @param bool|array $crop { + * Optional. 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'. + * @type string $1 The y crop position. Accepts 'top', 'center', or 'bottom'. + * } * @return true|WP_Error */ public function resize( $max_w, $max_h, $crop = false ) { @@ -190,7 +197,14 @@ class WP_Image_Editor_GD extends WP_Image_Editor { /** * @param int $max_w * @param int $max_h - * @param bool|array $crop + * @param bool|array $crop { + * Optional. 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'. + * @type string $1 The y crop position. Accepts 'top', 'center', or 'bottom'. + * } * @return resource|GdImage|WP_Error */ protected function _resize( $max_w, $max_h, $crop = false ) { diff --git a/wp-includes/class-wp-image-editor-imagick.php b/wp-includes/class-wp-image-editor-imagick.php index f29373f253..0e3c696f2f 100644 --- a/wp-includes/class-wp-image-editor-imagick.php +++ b/wp-includes/class-wp-image-editor-imagick.php @@ -320,7 +320,14 @@ class WP_Image_Editor_Imagick extends WP_Image_Editor { * * @param int|null $max_w Image width. * @param int|null $max_h Image height. - * @param bool|array $crop + * @param bool|array $crop { + * Optional. 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'. + * @type string $1 The y crop position. Accepts 'top', 'center', or 'bottom'. + * } * @return true|WP_Error */ public function resize( $max_w, $max_h, $crop = false ) { diff --git a/wp-includes/class-wp-image-editor.php b/wp-includes/class-wp-image-editor.php index 119d6e3bb0..da4fbab905 100644 --- a/wp-includes/class-wp-image-editor.php +++ b/wp-includes/class-wp-image-editor.php @@ -106,7 +106,14 @@ abstract class WP_Image_Editor { * * @param int|null $max_w Image width. * @param int|null $max_h Image height. - * @param bool|array $crop + * @param bool|array $crop { + * Optional. 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'. + * @type string $1 The y crop position. Accepts 'top', 'center', or 'bottom'. + * } * @return true|WP_Error */ abstract public function resize( $max_w, $max_h, $crop = false ); diff --git a/wp-includes/media.php b/wp-includes/media.php index 990aa272f4..0cece188dc 100644 --- a/wp-includes/media.php +++ b/wp-includes/media.php @@ -283,12 +283,14 @@ function image_downsize( $id, $size = 'medium' ) { * @param string $name Image size identifier. * @param int $width Optional. Image width in pixels. Default 0. * @param int $height Optional. Image height in pixels. Default 0. - * @param bool|array $crop Optional. 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. - * Array values must be in the format: array( x_crop_position, y_crop_position ) where: - * - x_crop_position accepts: 'left', 'center', or 'right'. - * - y_crop_position accepts: 'top', 'center', or 'bottom'. + * @param bool|array $crop { + * Optional. 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'. + * @type string $1 The y crop position. Accepts 'top', 'center', or 'bottom'. + * } */ function add_image_size( $name, $width = 0, $height = 0, $crop = false ) { global $_wp_additional_image_sizes; @@ -343,8 +345,14 @@ function remove_image_size( $name ) { * * @param int $width Image width in pixels. * @param int $height Image height in pixels. - * @param bool|array $crop Optional. Whether to crop images to specified width and height or resize. - * An array can specify positioning of the crop area. Default false. + * @param bool|array $crop { + * Optional. 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'. + * @type string $1 The y crop position. Accepts 'top', 'center', or 'bottom'. + * } */ function set_post_thumbnail_size( $width = 0, $height = 0, $crop = false ) { add_image_size( 'post-thumbnail', $width, $height, $crop ); @@ -511,22 +519,20 @@ function wp_constrain_dimensions( $current_width, $current_height, $max_width = * Calculates dimensions and coordinates for a resized image that fits * within a specified width and height. * - * Cropping behavior is dependent on the value of $crop: - * 1. If false (default), images will not be cropped. - * 2. If an array in the form of array( x_crop_position, y_crop_position ): - * - x_crop_position accepts 'left' 'center', or 'right'. - * - y_crop_position accepts 'top', 'center', or 'bottom'. - * Images will be cropped to the specified dimensions within the defined crop area. - * 3. If true, images will be cropped to the specified dimensions using center positions. - * * @since 2.5.0 * * @param int $orig_w Original width in pixels. * @param int $orig_h Original height in pixels. * @param int $dest_w New width in pixels. * @param int $dest_h New height in pixels. - * @param bool|array $crop Optional. Whether to crop image to specified width and height or resize. - * An array can specify positioning of the crop area. Default false. + * @param bool|array $crop { + * Optional. 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'. + * @type string $1 The y crop position. Accepts 'top', 'center', or 'bottom'. + * } * @return array|false Returned array matches parameters for `imagecopyresampled()`. False on failure. */ function image_resize_dimensions( $orig_w, $orig_h, $dest_w, $dest_h, $crop = false ) { @@ -670,11 +676,17 @@ function image_resize_dimensions( $orig_w, $orig_h, $dest_w, $dest_h, $crop = fa * * @since 2.5.0 * - * @param string $file File path. - * @param int $width Image width. - * @param int $height Image height. - * @param bool $crop Optional. Whether to crop image to specified width and height or resize. - * Default false. + * @param string $file File path. + * @param int $width Image width. + * @param int $height Image height. + * @param bool|array $crop { + * Optional. 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'. + * @type string $1 The y crop position. Accepts 'top', 'center', or 'bottom'. + * } * @return array|false Metadata array on success. False if no image was created. */ function image_make_intermediate_size( $file, $width, $height, $crop = false ) { diff --git a/wp-includes/version.php b/wp-includes/version.php index 00657de69b..5b098339a2 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -16,7 +16,7 @@ * * @global string $wp_version */ -$wp_version = '6.4-alpha-56415'; +$wp_version = '6.4-alpha-56416'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.