Core ticket idea = Split sideload_media_image function into 2

Readme.md

media_sideload_image could be a super useful function, except for one thing, it returns image HTML which is limited in what it can be used for.

What if it returned the attachment ID? That would be useful and media_sideload_image comes so close!

I've needed this a few times in the past and I've just had to copy/paste this function and edit it to return ID. Some examples of when I could have used this:

1. writing content importers
2. a plugin to sideload external images from post content comments on save

My proposal is to split media_sideload_image into 2 functions. The first, media_handle_sideload_image sideloads the image and returns the attachment ID. The second media_sideload_image returns the image HTML.

This maintains 100% backwards compatatbility, but lets developers use the more useful media_handle_sideload_image to do all kinds of exciting stuff with.

media-sideload.diff

diff --git wp-admin/includes/media.php wp-admin/includes/media.php
index 06cd1c1..5d6b6bd 100644
--- wp-admin/includes/media.php
+++ wp-admin/includes/media.php
@@ -791,7 +791,46 @@ function wp_media_upload_handler() {
 }
 
 /**
- * Download an image from the specified URL and attach it to a post.
+ * Download an image from the specified URL and attach it to a post, returning ID.
+ *
+ * @todo since
+ *
+ * @param string $file The URL of the image to download
+ * @param int $post_id The post ID the media is to be associated with
+ * @param string $desc Optional. Description of the image
+ * @return int|WP_Error Image attachment id.
+ */
+function media_handle_sideload_image($file, $post_id, $desc = null) {
+
+	// Download file to temp location
+	$tmp = download_url( $file );
+
+	// Set variables for storage
+	// fix file filename for query strings
+	preg_match( '/[^\?]+\.(jpe?g|jpe|gif|png)\b/i', $file, $matches );
+	$file_array['name'] = basename($matches[0]);
+	$file_array['tmp_name'] = $tmp;
+
+	// If error storing temporarily, unlink
+	if ( is_wp_error( $tmp ) ) {
+		@unlink($file_array['tmp_name']);
+		$file_array['tmp_name'] = '';
+	}
+
+	// do the validation and storage stuff
+	$id = media_handle_sideload( $file_array, $post_id, $desc );
+	// If error storing permanently, unlink
+	if ( is_wp_error($id) ) {
+		@unlink($file_array['tmp_name']);
+		return $id;
+	}
+
+	return absint( $id );
+
+}
+
+/**
+ * Download an image from the specified URL and attach it to a post, returning image HTML.
  *
  * @since 2.6.0
  *
@@ -801,39 +840,25 @@ function wp_media_upload_handler() {
  * @return string|WP_Error Populated HTML img tag on success
  */
 function media_sideload_image($file, $post_id, $desc = null) {
+
 	if ( ! empty($file) ) {
-		// Download file to temp location
-		$tmp = download_url( $file );
-
-		// Set variables for storage
-		// fix file filename for query strings
-		preg_match( '/[^\?]+\.(jpe?g|jpe|gif|png)\b/i', $file, $matches );
-		$file_array['name'] = basename($matches[0]);
-		$file_array['tmp_name'] = $tmp;
-
-		// If error storing temporarily, unlink
-		if ( is_wp_error( $tmp ) ) {
-			@unlink($file_array['tmp_name']);
-			$file_array['tmp_name'] = '';
-		}
 
-		// do the validation and storage stuff
-		$id = media_handle_sideload( $file_array, $post_id, $desc );
-		// If error storing permanently, unlink
-		if ( is_wp_error($id) ) {
-			@unlink($file_array['tmp_name']);
+		$id = media_handle_sideload_image( $file, $post_id, $desc );
+
+		if ( is_wp_error( $id ) ) {
 			return $id;
 		}
 
 		$src = wp_get_attachment_url( $id );
-	}
 
-	// Finally check to make sure the file has been saved, then return the html
-	if ( ! empty($src) ) {
-		$alt = isset($desc) ? esc_attr($desc) : '';
-		$html = "<img src='$src' alt='$alt' />";
-		return $html;
+		// Finally check to make sure the file has been saved, then return the html
+		if ( ! empty($src) ) {
+			$alt = isset($desc) ? esc_attr($desc) : '';
+			$html = "<img src='$src' alt='$alt' />";
+			return $html;
+		}
 	}
+
 }
 
 /**