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

$file string Required
The URL of the image to download.
$post_id int Optional
The post ID the media is to be associated with.
$desc string Optional
Description of the image.

Default: null

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

Default: 'html'


Top ↑

Return

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


Top ↑

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

 


Top ↑

Source

File: wp-admin/includes/media.php. View all references

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

Top ↑

Hooks



Top ↑

Changelog

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

Top ↑

User Contributed Notes

  1. Skip to note 3 content
    Contributed by andreas83b

    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 4 content
    Contributed by Mark Parnell

    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 5 content
    Contributed by MakeWebBetter

    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.