Docs: Correct the return type for wp_save_image_file().

SergeyBiryukov · SergeyBiryukov · commit d27deea5119b · 2022-06-21T11:13:17.000Z
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
diff --git 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 ) {
