From d27deea5119b577166546bb98b56b4b0c5ff735a Mon Sep 17 00:00:00 2001
From: Sergey Biryukov <sergeybiryukov@git.wordpress.org>
Date: Tue, 21 Jun 2022 11:13:17 +0000
Subject: [PATCH] Docs: Correct the return type for `wp_save_image_file()`.

Since WordPress 3.5, `wp_save_image_file()` uses `WP_Image_Editor` classes under the hood to save the images.

While the `save()` method in those instances returns `array|WP_Error` and is documented as such, the return type of the `wp_save_image_file()` function was still left as `bool`.

A better solution would be to adjust the function to return the documented boolean type. However, doing that after 20+ major WP releases would be a backward compatibility break, so the documentation is now updated instead.

Includes:
* Documenting the returned array using hash notation.
* Adding a `@since` note for the `$image` parameter expecting a `WP_Image_Editor` instance.
* Adding a `@since` note for the `$filesize` value being included in the returned array.

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

Props jrf, SergeyBiryukov.
See #55646.

git-svn-id: https://develop.svn.wordpress.org/trunk@53546 602fd350-edb4-49c9-b593-d223f7449a82
---
 src/wp-admin/includes/image-edit.php | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

diff --git a/src/wp-admin/includes/image-edit.php b/src/wp-admin/includes/image-edit.php
index 4cb0dc23d7..e814fc47e7 100644
--- a/src/wp-admin/includes/image-edit.php
+++ b/src/wp-admin/includes/image-edit.php
@@ -351,12 +351,26 @@ function wp_stream_image( $image, $mime_type, $attachment_id ) {
  * Saves image to file.
  *
  * @since 2.9.0
+ * @since 3.5.0 The `$image` parameter expects a `WP_Image_Editor` instance.
+ * @since 6.0.0 The `$filesize` value was added to the returned array.
  *
  * @param string          $filename  Name of the file to be saved.
  * @param WP_Image_Editor $image     The image editor instance.
  * @param string          $mime_type The mime type of the image.
  * @param int             $post_id   Attachment post ID.
- * @return bool True on success, false on failure.
+ * @return array|WP_Error|bool {
+ *     Array on success or WP_Error if the file failed to save.
+ *     When called with a deprecated value for the `$image` parameter,
+ *     i.e. a non-`WP_Image_Editor` image resource or `GdImage` instance,
+ *     the function will return true on success, false on failure.
+ *
+ *     @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.
+ * }
  */
 function wp_save_image_file( $filename, $image, $mime_type, $post_id ) {
 	if ( $image instanceof WP_Image_Editor ) {