Changeset 56416

Timestamp:

08/18/2023 05:54:41 PM (14 months ago)

Author:

johnbillion

Message:

Media: Standardise documentation of the $crop parameter for various media functions and methods.

See #58833

Location:

trunk/src/wp-includes

Files:

• class-wp-image-editor-gd.php (modified) (2 diffs)
• class-wp-image-editor-imagick.php (modified) (1 diff)
• class-wp-image-editor.php (modified) (1 diff)
• media.php (modified) (5 diffs)

trunk/src/wp-includes/class-wp-image-editor-gd.php

@@ -166 +166 @@
      * @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
      */
@@ -191 +198 @@
      * @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
      */

trunk/src/wp-includes/class-wp-image-editor-imagick.php

@@ -321 +321 @@
      * @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
      */

trunk/src/wp-includes/class-wp-image-editor.php

@@ -107 +107 @@
      * @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
      */

trunk/src/wp-includes/media.php

@@ -284 +284 @@
  * @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 ) {
@@ -344 +346 @@
  * @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 ) {
@@ -512 +520 @@
  * 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
  *
@@ -526 +526 @@
  * @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.
  */
@@ -671 +677 @@
  * @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.
  */