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'
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
| 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. |
A word of caution, the “description” that’s the third value for this function is actually the attachment’s “TITLE” and not it’s “DESCRIPTION”.
There is no support for adding the actual description with media_sideload_image.
Default Usage
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.
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
mp3to the list of extensions:Note however that you’ll probably want to set the
$return_typeparameter to eitherurlorid, as an image tag pointing to something other than an image won’t be very useful.media_sideload_image()checks the file extension as a basic security measure, but in a lot of cases external image URLs coming from APIs for example do not actually have one, while still serving a perfectly valid image.If you trust the source of the images, you can bypass the check by appending
#.jpgto the url like so:Find ID of attachment from src by using this function
$id = media_sideload_image( $url, $item_id, $desc, 'id' );