media_sideload_image

Downloads an image from the specified URL and attaches it to a post.

Description

(string|WP_Error) media_sideload_image( (string) $file, (int) $post_id, (constant) $desc = null, (string) $return = 'html' ); 

Returns (string|WP_Error)

Populated HTML img tag on success, WP_Error object otherwise.

Parameters (4)

0. $file (string)
The URL of the image to download.
1. $post_id (int)
The post ID the media is to be associated with.
2. $desc — Optional. (constant) => null
Description of the image.
3. $return — Optional. (string) => 'html'
Accepts html (image tag html) or src. (URL). Default html .

Usage

  1. if ( !function_exists( 'media_sideload_image' ) ) { 
  2.     require_once ABSPATH . '/wp-admin/includes/media.php'; 
  3. } 
  4.   
  5. // The URL of the image to download. 
  6. $file = ''; 
  7.   
  8. // The post ID the media is to be associated with. 
  9. $post_id = -1; 
  10.   
  11. // Optional. Description of the image. 
  12. $desc = null; 
  13.   
  14. // Optional. Accepts 'html' (image tag html) or 'src' (URL). Default 'html'. 
  15. $return = 'html'; 
  16.   
  17. // NOTICE! Understand what this does before running. 
  18. $result = media_sideload_image($file, $post_id, $desc, $return); 
  19.     

Defined (1)

The function is defined in the following location(s).

/wp-admin/includes/media.php  
  1. function media_sideload_image( $file, $post_id, $desc = null, $return = 'html' ) { 
  2.     if ( ! empty( $file ) ) { 
  3.  
  4.         // Set variables for storage, fix file filename for query strings. 
  5.         preg_match( '/[^\?]+\.(jpe?g|jpe|gif|png)\b/i', $file, $matches ); 
  6.         if ( ! $matches ) { 
  7.             return new WP_Error( 'image_sideload_failed', __( 'Invalid image URL' ) ); 
  8.         } 
  9.  
  10.         $file_array = array(); 
  11.         $file_array['name'] = basename( $matches[0] ); 
  12.  
  13.         // Download file to temp location. 
  14.         $file_array['tmp_name'] = download_url( $file ); 
  15.  
  16.         // Iferrorstoring temporarily, return the error. 
  17.         if ( is_wp_error( $file_array['tmp_name'] ) ) { 
  18.             return $file_array['tmp_name']; 
  19.         } 
  20.  
  21.         // Do the validation and storage stuff. 
  22.         $id = media_handle_sideload( $file_array, $post_id, $desc ); 
  23.  
  24.         // Iferrorstoring permanently, unlink. 
  25.         if ( is_wp_error( $id ) ) { 
  26.             @unlink( $file_array['tmp_name'] ); 
  27.             return $id; 
  28.         } 
  29.  
  30.         $src = wp_get_attachment_url( $id ); 
  31.     } 
  32.  
  33.     // Finally, check to make sure the file has been saved, then return the HTML. 
  34.     if ( ! empty( $src ) ) { 
  35.         if ( $return === 'src' ) { 
  36.             return $src; 
  37.         } 
  38.  
  39.         $alt = isset( $desc ) ? esc_attr( $desc ) : ''; 
  40.         $html = "<img src='$src' alt='$alt' />"; 
  41.         return $html; 
  42.     } else { 
  43.         return new WP_Error( 'image_sideload_failed' ); 
  44.     } 
  45. }