media_handle_sideload()
Handles a side-loaded file in the same way as an uploaded file is handled by media_handle_upload().
Uses: wp_handle_sideload(), wp_insert_attachment(), wp_read_image_metadata(), wp_update_attachment_metadata(), wp_generate_attachment_metadata()
Used By: media_sideload_image()
No Hooks.
Return
Int|WP_Error
. The ID of the attachment or a WP_Error on failure.
Usage
media_handle_sideload( $file_array, $post_id, $desc, $post_data );
- $file_array(string[]) (required)
- Array that represents a $_FILES upload array.
- $post_id(int)
- The post ID the media is associated with.
- $desc(string)
- Description of the side-loaded file.
Default: null - $post_data(array)
- Post data to override.
Default: empty array
Examples
#1 Uploading a file by URL
This example shows how to work with the function. This code will download an image from an external source, add it to the WordPress media library, and attach it to the specified post:
// the frontend needs these files //require_once ABSPATH . 'wp-admin/includes/image.php'; //require_once ABSPATH . 'wp-admin/includes/file.php'; //require_once ABSPATH . 'wp-admin/includes/media.php'; $url = 'http://s.w.org/style/images/wp-header-logo.png'; $post_id = 3061; $desc = "WordPress Logo"; // Load file $tmp = download_url( $url ); /** * Check for download errors * if there are error unlink the temp file name */ if ( is_wp_error( $tmp ) ) { @unlink( $tmp ); return $tmp; } //Set file data $file_array = [ 'name' => basename( $url ), // ex: wp-header-logo.png 'tmp_name' => $tmp, 'error' => 0, 'size' => filesize($tmp), ]; // upload the file $id = media_handle_sideload( $file_array, $post_id, $desc ); // if there is an error if( is_wp_error( $id ) ) { @unlink($file_array['tmp_name']); return $id->get_error_messages(); } // delete the temporary file @unlink( $tmp ); // that's it, the file is loaded and should appear in the admin panel in the media files
No we can get the url of the sideloaded file $value now contains the file url in WordPress $id is the attachment id:
$value = wp_get_attachment_url( $id ); // Now you can do something with $value (or $id)
#2 Uploading a file by URL without linking it to any post
// the frontend needs these files //require_once ABSPATH . 'wp-admin/includes/image.php'; //require_once ABSPATH . 'wp-admin/includes/file.php'; //require_once ABSPATH . 'wp-admin/includes/media.php'; $url = "http://s.w.org/style/images/wp-header-logo.png"; $desc = "WordPress Logo"; // load the file $tmp = download_url( $url ); if ( ! is_wp_error( $tmp ) ) { // correct the filename in the query lines. $file_array = [ 'name' => basename( $url ), 'tmp_name' => $tmp ]; $id = media_handle_sideload( $file_array, 0 ); // if there is an error if( is_wp_error( $id ) ){ echo $id->get_error_messages(); } } // delete the temporary file @unlink( $tmp );
#3 Uploading an external image and setting the thumbnail of the post
A function that will download an external image from a specified URL, save it to the uploads directory and attach it to the post as a thumbnail:
// initialize function $post_id = 3061; $file = 'http://s.w.org/style/images/wp-header-logo.png?1'; if( is_single( $post_id ) ){ my_sideload_image( $post_id, $file, $desc = 'Image description' ); } // function code function my_sideload_image( $post_id, $file, $desc = null ){ global $debug; // defined outside the function as true if( ! function_exists('media_handle_sideload') ) { require_once ABSPATH . 'wp-admin/includes/image.php'; require_once ABSPATH . 'wp-admin/includes/file.php'; require_once ABSPATH . 'wp-admin/includes/media.php'; } // Load the file into a temporary directory $tmp = download_url( $file ); // Set variables for placement $file_array = [ 'name' => basename( $file ), 'tmp_name' => $tmp ]; // Delete the temporary file, in case of an error if ( is_wp_error( $tmp ) ) { $file_array['tmp_name'] = ''; if( $debug ) echo 'Error no temporary file! <br />'; } // debug checks if( $debug ){ echo 'File array: <br />'; var_dump( $file_array ); echo '<br /> Post id: ' . $post_id . '<br />'; } $id = media_handle_sideload( $file_array, $post_id, $desc ); // Check the function if ( is_wp_error( $id ) ) { var_dump( $id->get_error_messages() ); } else { update_post_meta( $post_id, '_thumbnail_id', $id ); } // delete the temporary file @unlink( $tmp ); }
Changelog
Since 2.6.0 | Introduced. |
Since 5.3.0 | The $post_id parameter was made optional. |