Changeset 53547

Timestamp:

06/21/2022 11:16:09 AM (3 years ago)

Author:

SergeyBiryukov

Message:

Docs: Improve documentation for WP_Image_Editor::save() and related functions.

Includes:

• Documenting the returned array using hash notation.
• Adding a @since note for the $filesize value being included in the returned array.

This affects:

• wp_generate_attachment_metadata()
• wp_get_attachment_metadata()
• WP_Image_Editor::save()
• WP_Image_Editor_GD::save() and ::_save()
• WP_Image_Editor_Imagick::save() and ::_save()

Follow-up to [22094], [22619], [52837], [53546].

See #55646.

Location:

trunk/src

Files:

• wp-admin/includes/image.php (modified) (3 diffs)
• wp-includes/class-wp-image-editor-gd.php (modified) (2 diffs)
• wp-includes/class-wp-image-editor-imagick.php (modified) (2 diffs)
• wp-includes/class-wp-image-editor.php (modified) (1 diff)
• wp-includes/post.php (modified) (1 diff)

trunk/src/wp-admin/includes/image.php

@@ -191 +191 @@
  *
  * @since 5.3.0
+ * @since 6.0.0 The `$filesize` value was added to the returned array.
  * @access private
  *
@@ -212 +213 @@
     $image_meta['file'] = _wp_relative_upload_path( $new_file );
 
+    // Add image file size.
+    $image_meta['filesize'] = wp_filesize( $new_file );
+
     // Store the original image file name in image_meta.
     $image_meta['original_image'] = wp_basename( $original_file );
-
-    // Add image file size.
-    $image_meta['filesize'] = wp_filesize( $new_file );
 
     return $image_meta;
@@ -478 +479 @@
  *
  * @since 2.1.0
+ * @since 6.0.0 The `$filesize` value was added to the returned array.
  *
  * @param int    $attachment_id Attachment ID to process.

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

@@ -426 +426 @@
      * @since 5.9.0 Renamed `$filename` to `$destfilename` to match parent class
      *              for PHP 8 named parameter support.
+     * @since 6.0.0 The `$filesize` value was added to the returned array.
      *
      * @param string|null $destfilename Optional. Destination filename. Default null.
      * @param string|null $mime_type    Optional. The mime-type. Default null.
-     * @return array|WP_Error {'path'=>string, 'file'=>string, 'width'=>int, 'height'=>int, 'mime-type'=>string}
+     * @return array|WP_Error {
+     *     Array on success or WP_Error if the file failed to save.
+     *
+     *     @type string $path      Path to the image file.
+     *     @type string $file      Name of the image file.
+     *     @type int    $width     Image width.
+     *     @type int    $height    Image height.
+     *     @type string $mime-type The mime type of the image.
+     *     @type int    $filesize  File size of the image.
+     * }
      */
     public function save( $destfilename = null, $mime_type = null ) {
@@ -443 +453 @@
 
     /**
+     * @since 3.5.0
+     * @since 6.0.0 The `$filesize` value was added to the returned array.
+     *
      * @param resource|GdImage $image
      * @param string|null      $filename
      * @param string|null      $mime_type
-     * @return array|WP_Error
+     * @return array|WP_Error {
+     *     Array on success or WP_Error if the file failed to save.
+     *
+     *     @type string $path      Path to the image file.
+     *     @type string $file      Name of the image file.
+     *     @type int    $width     Image width.
+     *     @type int    $height    Image height.
+     *     @type string $mime-type The mime type of the image.
+     *     @type int    $filesize  File size of the image.
+     * }
      */
     protected function _save( $image, $filename = null, $mime_type = null ) {

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

@@ -662 +662 @@
      *
      * @since 3.5.0
+     * @since 6.0.0 The `$filesize` value was added to the returned array.
      *
      * @param string $destfilename Optional. Destination filename. Default null.
      * @param string $mime_type    Optional. The mime-type. Default null.
-     * @return array|WP_Error {'path'=>string, 'file'=>string, 'width'=>int, 'height'=>int, 'mime-type'=>string}
+     * @return array|WP_Error {
+     *     Array on success or WP_Error if the file failed to save.
+     *
+     *     @type string $path      Path to the image file.
+     *     @type string $file      Name of the image file.
+     *     @type int    $width     Image width.
+     *     @type int    $height    Image height.
+     *     @type string $mime-type The mime type of the image.
+     *     @type int    $filesize  File size of the image.
+     * }
      */
     public function save( $destfilename = null, $mime_type = null ) {
@@ -685 +695 @@
 
     /**
+     * @since 3.5.0
+     * @since 6.0.0 The `$filesize` value was added to the returned array.
+     *
      * @param Imagick $image
      * @param string  $filename
      * @param string  $mime_type
-     * @return array|WP_Error
+     * @return array|WP_Error {
+     *     Array on success or WP_Error if the file failed to save.
+     *
+     *     @type string $path      Path to the image file.
+     *     @type string $file      Name of the image file.
+     *     @type int    $width     Image width.
+     *     @type int    $height    Image height.
+     *     @type string $mime-type The mime type of the image.
+     *     @type int    $filesize  File size of the image.
+     * }
      */
     protected function _save( $image, $filename = null, $mime_type = null ) {

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

@@ -76 +76 @@
      *
      * @since 3.5.0
+     * @since 6.0.0 The `$filesize` value was added to the returned array.
      * @abstract
      *
      * @param string $destfilename Optional. Destination filename. Default null.
      * @param string $mime_type    Optional. The mime-type. Default null.
-     * @return array|WP_Error {'path'=>string, 'file'=>string, 'width'=>int, 'height'=>int, 'mime-type'=>string}
+     * @return array|WP_Error {
+     *     Array on success or WP_Error if the file failed to save.
+     *
+     *     @type string $path      Path to the image file.
+     *     @type string $file      Name of the image file.
+     *     @type int    $width     Image width.
+     *     @type int    $height    Image height.
+     *     @type string $mime-type The mime type of the image.
+     *     @type int    $filesize  File size of the image.
+     * }
      */
     abstract public function save( $destfilename = null, $mime_type = null );

trunk/src/wp-includes/post.php

@@ -6509 +6509 @@
  *
  * @since 2.1.0
+ * @since 6.0.0 The `$filesize` value was added to the returned array.
  *
  * @param int  $attachment_id Attachment post ID. Defaults to global $post.