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.
Contents
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'
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
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' );
}
}
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. |
User Contributed Notes
You must log in before being able to contribute a note or feedback.
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
mp3
to the list of extensions:Note however that you’ll probably want to set the
$return_type
parameter to eitherurl
orid
, as an image tag pointing to something other than an image won’t be very useful.Find ID of attachment from src by using this function
Top ↑
Feedback
From WP 4.8 it’s possible to have directly the ‘id’ (4th param):
$id = media_sideload_image( $url, $item_id, $desc, 'id' );
— By eventualo —