return option for media_sideload_image

[slbmeh]

An optional parameter to return the attachment id opposed to the html would be beneficial to those attempting to make use of this functionality outside of press this.

Ticket: #11993 has an enhancement suggestion to allow adding thumbnails from URL. I have written a solution for this enhancement, and the result duplicates the functionality of media_sideload_image() setting the post thumbnail opposed to returning the image html markup.

Attached patch reuses the existing variable $html which would lead to HTML always being returned. Also the variable type given in the PHPDoc is wrong.

Use $return_html instead

Related, #15432?

abstract out the sideloading of the image so the ID can be accessed

Here is an alternative implementation. Instead of the additional arg to change the return, refactor the function into two functions. One returns the ID (more efficient, since if you just need the ID it doesn't need to call wp_get_attachment_url(), etc.), the other calls this function to get the ID and returns the HTML (maintains current behavior).

Without this change, it is difficult to implement the following functionality while utilizing core functions:

1. sideload an image
2. set the image as the featured images for the post

Replying to alexkingorg:

Without this change, it is difficult to implement the following functionality while utilizing core functions:

1. sideload an image
2. set the image as the featured images for the post

I had to reimplement media_sideload_image() a couple of times for this exact use case.

The approach in wp-sideload-media-id-ak.diff​ makes sense to me.

Better abstracted function name

+1 to wp_sideload_image().

I like it, but I would think we'd want to call the variable $url instead of $file to avoid confusion? Happy to write a patch revision if anyone else agrees.

Replying to georgestephanis:

I like it, but I would think we'd want to call the variable $url instead of $file to avoid confusion?

I think $file was used for consistency with media_sideload_image().

Some explanation of the existing stack:

• wp_handle_upload() is the underlying function that handles an upload of any file in WordPress, writing it to disk, etc.
• wp_handle_sideload() is the equivalent underlying function.
• media_handle_upload() takes $_POST/$_FILES and passes it to wp_upload_image().
• media_handle_sideload() is the equivalent function, taking a $_FILES array and passing it to wp_sideload_image().

Then, there is media_sideload_image(), which is more or less a glorified wrapper for media_handle_sideload():

• It accepts a URL, which then goes to download_url(), builds a $_FILES-like array of local files, then passes it along.
• Only works on images.
• Returns an <img> tag.

Now, media_handle_upload()'s first argument is $file_id, which is the key to the corresponding file in $_FILES. But media_handle_sideload() takes the full array. This is because it isn't actually using $_FILES, instead just taking an argument that looks like it.

Since media_handle_sideload() takes an array currently, we can actually get away with allowing a URL to be passed instead. The benefits here are many fold:

• We don't need to introduce a new function, which would cause imbalance to the current stack.
• media_handle_sideload() ends up taking a saner argument of a URL to sideload.
• The existing function already works on any kind of file, not just images.
• The existing function already returns an ID.

We're not prevented, of course, from adding new highest-level functions like wp_upload_media() (or wp_upload_file()) and wp_sideload_media() in the future.

Doing this will probably mean a deprecation of media_sideload_image() in favor of media_handle_sideload(). Its single usage in Press This could become a call to media_handle_sideload() followed by a call to wp_get_attachment_url(), as it does now.

Suggested patch attached. Since this is not critical and there exist workarounds (namely, using download_url() and media_handle_sideload() manually), moving to 3.6. Happy to resolve this early.