From b8290da037a8910760c571fba5174fbe07907463 Mon Sep 17 00:00:00 2001 From: Sergey Biryukov Date: Tue, 21 Jun 2022 11:18:17 +0000 Subject: [PATCH] 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. Built from https://develop.svn.wordpress.org/trunk@53547 git-svn-id: http://core.svn.wordpress.org/trunk@53136 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-admin/includes/image.php | 8 +++--- wp-includes/class-wp-image-editor-gd.php | 26 +++++++++++++++++-- wp-includes/class-wp-image-editor-imagick.php | 26 +++++++++++++++++-- wp-includes/class-wp-image-editor.php | 12 ++++++++- wp-includes/post.php | 1 + wp-includes/version.php | 2 +- 6 files changed, 66 insertions(+), 9 deletions(-) diff --git a/wp-admin/includes/image.php b/wp-admin/includes/image.php index 74d08bf634..1a9c9e2e9c 100644 --- a/wp-admin/includes/image.php +++ b/wp-admin/includes/image.php @@ -190,6 +190,7 @@ function wp_update_image_subsizes( $attachment_id ) { * Updates the attached file and image meta data when the original image was edited. * * @since 5.3.0 + * @since 6.0.0 The `$filesize` value was added to the returned array. * @access private * * @param array $saved_data The data returned from WP_Image_Editor after successfully saving an image. @@ -211,12 +212,12 @@ function _wp_image_meta_replace_original( $saved_data, $original_file, $image_me // Make the file path relative to the upload dir. $image_meta['file'] = _wp_relative_upload_path( $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 ); + // Store the original image file name in image_meta. + $image_meta['original_image'] = wp_basename( $original_file ); + return $image_meta; } @@ -477,6 +478,7 @@ function _wp_make_subsizes( $new_sizes, $file, $image_meta, $attachment_id ) { * Generate attachment meta data and create image sub-sizes for images. * * @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. * @param string $file Filepath of the attached image. diff --git a/wp-includes/class-wp-image-editor-gd.php b/wp-includes/class-wp-image-editor-gd.php index 0d2965d925..03525ce943 100644 --- a/wp-includes/class-wp-image-editor-gd.php +++ b/wp-includes/class-wp-image-editor-gd.php @@ -425,10 +425,20 @@ class WP_Image_Editor_GD extends WP_Image_Editor { * @since 3.5.0 * @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 ) { $saved = $this->_save( $this->image, $destfilename, $mime_type ); @@ -442,10 +452,22 @@ class WP_Image_Editor_GD extends WP_Image_Editor { } /** + * @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 ) { list( $filename, $extension, $mime_type ) = $this->get_output_format( $filename, $mime_type ); diff --git a/wp-includes/class-wp-image-editor-imagick.php b/wp-includes/class-wp-image-editor-imagick.php index 88614fe1ae..f413387233 100644 --- a/wp-includes/class-wp-image-editor-imagick.php +++ b/wp-includes/class-wp-image-editor-imagick.php @@ -661,10 +661,20 @@ class WP_Image_Editor_Imagick extends WP_Image_Editor { * Saves current image to file. * * @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 ) { $saved = $this->_save( $this->image, $destfilename, $mime_type ); @@ -684,10 +694,22 @@ class WP_Image_Editor_Imagick extends WP_Image_Editor { } /** + * @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 ) { list( $filename, $extension, $mime_type ) = $this->get_output_format( $filename, $mime_type ); diff --git a/wp-includes/class-wp-image-editor.php b/wp-includes/class-wp-image-editor.php index b64ae0be7f..caa3092d36 100644 --- a/wp-includes/class-wp-image-editor.php +++ b/wp-includes/class-wp-image-editor.php @@ -75,11 +75,21 @@ abstract class WP_Image_Editor { * Saves current image to file. * * @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 ); diff --git a/wp-includes/post.php b/wp-includes/post.php index cbf3e6e59a..23719feadd 100644 --- a/wp-includes/post.php +++ b/wp-includes/post.php @@ -6508,6 +6508,7 @@ function wp_delete_attachment_files( $post_id, $meta, $backup_sizes, $file ) { * Retrieves attachment metadata for attachment ID. * * @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. * @param bool $unfiltered Optional. If true, filters are not run. Default false. diff --git a/wp-includes/version.php b/wp-includes/version.php index 9012835eae..b3ab5495f3 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -16,7 +16,7 @@ * * @global string $wp_version */ -$wp_version = '6.1-alpha-53546'; +$wp_version = '6.1-alpha-53547'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.