media_sideload_image() │ WP 2.6.0

Uploads an image to the WP media library from the specified URL and attaches it to a post.

In other words, the function uploads an image from an external URL to the WP media library, attaches it to the specified post and returns <img> or the URL of the uploaded image.

For the function to work in the Front-end the following files are required:

require_once ABSPATH . 'wp-admin/includes/media.php';
require_once ABSPATH . 'wp-admin/includes/file.php';
require_once ABSPATH . 'wp-admin/includes/image.php';

If you need to upload any file type (and not only an image), use a similar function: media_handle_sideload().

Uses: media_handle_sideload(), download_url()
Hooks from the function

Returns

String|Int|WP_Error.

  • string - HTML of the img tag, when $return = html (by default).
  • string - URL of the uploaded attachment, when $return = src.
  • int - ID of the uploaded attachment, when $return = id.
  • WP_Error - error object, with the error message.

Usage

media_sideload_image( $file, $post_id, $desc, $return_type );
$file(string) (required)
URL of the image to upload.
$post_id(int) (required)
ID of the post to which the uploaded image file will be attached. 0 — do not attach.
$desc(string|null)

The image title. If not specified, the title will be taken from the URL or from the image metadata.

Note: This parameter actually sets the attachment "TITLE", not the "DESCRIPTION". There is no way to set a real attachment description using this function.

Default: null

$return_type(string)

What to return. Can be:

  • html - the image IMG tag
  • src - just the URL
  • id - attachment ID. Since WP 4.8

Default: 'html'

Examples

0

#1 Download the image file for the post from an external URL 

// when we're at the front
require_once ABSPATH . 'wp-admin/includes/media.php';
require_once ABSPATH . 'wp-admin/includes/file.php';
require_once ABSPATH . 'wp-admin/includes/image.php';

$url = 'http://s.w.org/style/images/wp-header-logo.png';
$post_id = 3061;
$desc = "WordPress Logo";

$img_tag = media_sideload_image( $url, $post_id, $desc );

if( is_wp_error( $img_tag ) ){
	echo $img_tag->get_error_message();
}
else {
	// file added 
	echo $img_tag;
}

The same example, but in a different implementation, is shown in the description of media_handle_sideload() function.

Changelog

Since 2.6.0 Introduced.
Since 4.2.0 Introduced the $return_type parameter.
Since 4.8.0 Introduced the 'id' option for the $return_type parameter.
Since 5.3.0 The $post_id parameter was made optional.
Since 5.4.0 The original URL of the attachment is stored in the _source_url post meta value.
Since 5.8.0 Added 'webp' to the default list of allowed file extensions.

media_sideload_image() code WP 7.0

wp-admin/includes/media.php 
function media_sideload_image( $file, $post_id = 0, $desc = null, $return_type = 'html' ) {
	if ( ! empty( $file ) ) {

		$allowed_extensions = array( 'jpg', 'jpeg', 'jpe', 'png', 'gif', 'webp' );

		/**
		 * Filters the list of allowed file extensions when sideloading an image from a URL.
		 *
		 * The default allowed extensions are:
		 *
		 *  - `jpg`
		 *  - `jpeg`
		 *  - `jpe`
		 *  - `png`
		 *  - `gif`
		 *  - `webp`
		 *
		 * @since 5.6.0
		 * @since 5.8.0 Added 'webp' to the default list of allowed file extensions.
		 *
		 * @param string[] $allowed_extensions Array of allowed file extensions.
		 * @param string   $file               The URL of the image to download.
		 */
		$allowed_extensions = apply_filters( 'image_sideload_extensions', $allowed_extensions, $file );
		$allowed_extensions = array_map( 'preg_quote', $allowed_extensions );

		// Set variables for storage, fix file filename for query strings.
		preg_match( '/[^\?]+\.(' . implode( '|', $allowed_extensions ) . ')\b/i', $file, $matches );

		if ( ! $matches ) {
			return new WP_Error( 'image_sideload_failed', __( 'Invalid image URL.' ) );
		}

		$file_array         = array();
		$file_array['name'] = wp_basename( $matches[0] );

		// Download file to temp location.
		$file_array['tmp_name'] = download_url( $file );

		// If error storing temporarily, return the error.
		if ( is_wp_error( $file_array['tmp_name'] ) ) {
			return $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;
		}

		// Store the original attachment source in meta.
		add_post_meta( $id, '_source_url', $file );

		// If attachment ID was requested, return it.
		if ( 'id' === $return_type ) {
			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 ) ) {
		if ( 'src' === $return_type ) {
			return $src;
		}

		$alt  = isset( $desc ) ? esc_attr( $desc ) : '';
		$html = "<img src='$src' alt='$alt' />";

		return $html;
	} else {
		return new WP_Error( 'image_sideload_failed' );
	}
}

upload download (file system)