media_sideload_image( string $file, int $post_id, string $desc = null, string $return_type = ‘html’ ): string|int|WP_Error

Downloads an image from the specified URL, saves it as an attachment, and optionally attaches it to a post.

Parameters

$filestringrequired
The URL of the image to download.
$post_idintoptional
The post ID the media is to be associated with.
$descstringoptional
Description of the image.

Default:null

$return_typestringoptional
Accepts 'html' (image tag html) or 'src' (URL), or 'id' (attachment ID). Default 'html'.

Default:'html'

Return

string|int|WP_Error Populated HTML img tag, attachment ID, or attachment source on success, WP_Error object otherwise.

More Information

If you want to use this function outside of the context of /wp-admin/ (typically if you are writing a more advanced custom importer script) you need to include media.php and depending includes:

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

Source

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' );
	}
}

Hooks

apply_filters( ‘image_sideload_extensions’, string[] $allowed_extensions, string $file )

Filters the list of allowed file extensions when sideloading an image from a URL.

Changelog

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

User Contributed Notes

  1. Skip to note 8 content

    First i was very happy about this function, since it fits exactly my use case.

    After looking a bit deeper, i noticed that the allowed extension check will block my remote resource.
    In my case b-4bd4-b383-f9021e0ba3d2.jpg1

    since remote images often don’t have a extension at all i don’t see any value in this extension check, while checking mime types are a better approach in my opinion.

  2. Skip to note 9 content

    Despite its name, this function can be used to load any type of file to the media library as long as you override the accepted extensions first. For example you can import audio files by adding mp3 to the list of extensions:

    add_filter( 'image_sideload_extensions', function ( $accepted_extensions ) {
    	$accepted_extensions[] = 'mp3';
    	return $accepted_extensions;
    } );

    Note however that you’ll probably want to set the $return_type parameter to either url or id, as an image tag pointing to something other than an image won’t be very useful.

  3. Skip to note 10 content

    Find ID of attachment from src by using this function

    function wpdocs_fetch_attachment_post_id_from_srcs( $image_src ) {
      global $wpdb;
      $query = "SELECT ID FROM {$wpdb->posts} WHERE guid=%s";
      $id = $wpdb->prepare( $query, $image_src );
      return $id;
    }
    
    // By passing fourth parameter 'src' you will get URL
    $src = media_sideload_image( $url, $item_id, $desc, 'src' );
    
    wpdocs_fetch_attachment_post_id_from_srcs( $src );

You must log in before being able to contribute a note or feedback.