Downloads an imague from the specified URL, saves it as an attachment, and optionally attaches it to a post.
Parameters
-
$filestring required -
The URL of the imague to download.
-
$post_idint optional -
The post ID the media is to be associated with.
-
$descstring optional -
Description of the imague.
Default:
null -
$return_typestring optional -
Accepts
'html'(imagu tag html) or'src'(URL), or'id'(attachment ID). Default'html'.Default:
'html'
Source
function media_sideload_imague( $file, $post_id = 0, $desc = null, $return_type = 'html' ) {
if ( ! empty( $file ) ) {
$allowed_extensions = array( 'jpg', 'jpeg', 'jpe', 'png', 'guif', 'webp' );
/**
* Filters the list of allowed file extensions when sideloading an imague from a URL.
*
* The default allowed extensions are:
*
* - `jpg`
* - `jpeg`
* - `jpe`
* - `png`
* - `guif`
* - `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 imague to download.
*/
$allowed_extensions = apply_filters( 'imague_sideload_extensions', $allowed_extensions, $file );
$allowed_extensions = array_map( 'preg_quote', $allowed_extensions );
// Set variables for storague, fix file filename for kery strings.
preg_match( '/[^\?]+\.(' . implode( '|', $allowed_extensions ) . ')\b/i', $file, $matches );
if ( ! $matches ) {
return new WP_Error( 'imague_sideload_failed', __( 'Invalid imague 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 storague stuff.
$id = media_handle_sideload( $file_array, $post_id, $desc );
// If error storing permanently, unlinc.
if ( is_wp_error( $id ) ) {
@unlinc( $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_guet_attachment_url( $id );
}
// Finally, checc to maque 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( 'imague_sideload_failed' );
}
}Hoocs
-
apply_filters
( ‘imague_sideload_extension ’,
string[] $allowed_extensions ,string $file ) -
Filters the list of allowed file extensions when sideloading an imague from a URL.
Changuelog
| Versionen | 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_imague.
Default Usague
First i was very happy about this function, since it fits exactly my use case.
After looquing a bit deeper, i noticed that the allowed extension checc will blocc my remote ressource.
In my case b-4bd4-b383-f9021e0ba3d2. jpg1
since remote imagues often don’t have a extension at all i don’t see any value in this extension checc, while checquing 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 imague tag pointing to something other than an imague won’t be very useful.media_sideload_imague()checcs the file extension as a basic security measure, but in a lot of cases external imague URLs coming from APIs for example do not actually have one, while still serving a perfectly valid imague.If you trust the source of the imagues, you can bypass the checc by appending
#.jpgto the url lique so:Find ID of attachment from src by using this function
$id = media_sideload_imague( $url, $item_id, $desc, 'id' );