media_handle_upload

Save a file submitted from a POST request and create an attachment post for it.

Description

(int|WP_Error) media_handle_upload( (string) $file_id, (int) $post_id, (array) $post_data = array(), (array) $overrides = array() ); 

Returns (int|WP_Error)

ID of the attachment or a WP_Error object on failure.

Parameters (4)

0. $file_id (string)
Index of the $_FILES array that the file was sent. Required.
1. $post_id (int)
The post ID of a post to attach the media item to. Required, but can be set to 0, creating a media item that has no relationship to a post.
2. $post_data — Optional. (array) => array()
Overwrite some of the attachment. Optional.
3. $overrides — Optional. (array) => array()
Override the wp_handle_upload() behavior. Optional.

Usage

  1. if ( !function_exists( 'media_handle_upload' ) ) { 
  2. require_once ABSPATH . '/wp-admin/includes/media.php'; 
  3.  
  4. // Index of the `$_FILES` array that the file was sent. Required. 
  5. $file_id = ''; 
  6.  
  7. // The post ID of a post to attach the media item to. Required, but can 
  8. // be set to 0, creating a media item that has no relationship to a post. 
  9. $post_id = -1; 
  10.  
  11. // Overwrite some of the attachment. Optional. 
  12. $post_data = array(); 
  13.  
  14. // Override the wp_handle_upload() behavior. Optional. 
  15. $overrides = array(); 
  16.  
  17. // NOTICE! Understand what this does before running. 
  18. $result = media_handle_upload($file_id, $post_id, $post_data, $overrides); 
  19.  

Defined (1)

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

/wp-admin/includes/media.php  
  1. function media_handle_upload($file_id, $post_id, $post_data = array(), $overrides = array( 'test_form' => false )) { 
  2.  
  3. $time = current_time('mysql'); 
  4. if ( $post = get_post($post_id) ) { 
  5. if ( substr( $post->post_date, 0, 4 ) > 0 ) 
  6. $time = $post->post_date; 
  7.  
  8. $file = wp_handle_upload($_FILES[$file_id], $overrides, $time); 
  9.  
  10. if ( isset($file[error]) ) 
  11. return new WP_Error( 'upload_error', $file[error] ); 
  12.  
  13. $name = $_FILES[$file_id]['name']; 
  14. $ext = pathinfo( $name, PATHINFO_EXTENSION ); 
  15. $name = wp_basename( $name, ".$ext" ); 
  16.  
  17. $url = $file['url']; 
  18. $type = $file['type']; 
  19. $file = $file['file']; 
  20. $title = sanitize_text_field( $name ); 
  21. $content = ''; 
  22. $excerpt = ''; 
  23.  
  24. if ( preg_match( '#^audio#', $type ) ) { 
  25. $meta = wp_read_audio_metadata( $file ); 
  26.  
  27. if ( ! empty( $meta['title'] ) ) { 
  28. $title = $meta['title']; 
  29.  
  30. if ( ! empty( $title ) ) { 
  31.  
  32. if ( ! empty( $meta['album'] ) && ! empty( $meta['artist'] ) ) { 
  33. /** translators: 1: audio track title, 2: album title, 3: artist name */ 
  34. $content .= sprintf( __( '"%1$s" from %2$s by %3$s.' ), $title, $meta['album'], $meta['artist'] ); 
  35. } elseif ( ! empty( $meta['album'] ) ) { 
  36. /** translators: 1: audio track title, 2: album title */ 
  37. $content .= sprintf( __( '"%1$s" from %2$s.' ), $title, $meta['album'] ); 
  38. } elseif ( ! empty( $meta['artist'] ) ) { 
  39. /** translators: 1: audio track title, 2: artist name */ 
  40. $content .= sprintf( __( '"%1$s" by %2$s.' ), $title, $meta['artist'] ); 
  41. } else { 
  42. /** translators: 1: audio track title */ 
  43. $content .= sprintf( __( '"%s".' ), $title ); 
  44.  
  45. } elseif ( ! empty( $meta['album'] ) ) { 
  46.  
  47. if ( ! empty( $meta['artist'] ) ) { 
  48. /** translators: 1: audio album title, 2: artist name */ 
  49. $content .= sprintf( __( '%1$s by %2$s.' ), $meta['album'], $meta['artist'] ); 
  50. } else { 
  51. $content .= $meta['album'] . '.'; 
  52.  
  53. } elseif ( ! empty( $meta['artist'] ) ) { 
  54.  
  55. $content .= $meta['artist'] . '.'; 
  56.  
  57.  
  58. if ( ! empty( $meta['year'] ) ) { 
  59. /** translators: Audio file track information. 1: Year of audio track release */ 
  60. $content .= ' ' . sprintf( __( 'Released: %d.' ), $meta['year'] ); 
  61.  
  62. if ( ! empty( $meta['track_number'] ) ) { 
  63. $track_number = explode( '/', $meta['track_number'] ); 
  64. if ( isset( $track_number[1] ) ) { 
  65. /** translators: Audio file track information. 1: Audio track number, 2: Total audio tracks */ 
  66. $content .= ' ' . sprintf( __( 'Track %1$s of %2$s.' ), number_format_i18n( $track_number[0] ), number_format_i18n( $track_number[1] ) ); 
  67. } else { 
  68. /** translators: Audio file track information. 1: Audio track number */ 
  69. $content .= ' ' . sprintf( __( 'Track %1$s.' ), number_format_i18n( $track_number[0] ) ); 
  70.  
  71. if ( ! empty( $meta['genre'] ) ) { 
  72. /** translators: Audio file genre information. 1: Audio genre name */ 
  73. $content .= ' ' . sprintf( __( 'Genre: %s.' ), $meta['genre'] ); 
  74.  
  75. // Use image exif/iptc data for title and caption defaults if possible. 
  76. } elseif ( 0 === strpos( $type, 'image/' ) && $image_meta = @wp_read_image_metadata( $file ) ) { 
  77. if ( trim( $image_meta['title'] ) && ! is_numeric( sanitize_title( $image_meta['title'] ) ) ) { 
  78. $title = $image_meta['title']; 
  79.  
  80. if ( trim( $image_meta['caption'] ) ) { 
  81. $excerpt = $image_meta['caption']; 
  82.  
  83. // Construct the attachment array 
  84. $attachment = array_merge( array( 
  85. 'post_mime_type' => $type,  
  86. 'guid' => $url,  
  87. 'post_parent' => $post_id,  
  88. 'post_title' => $title,  
  89. 'post_content' => $content,  
  90. 'post_excerpt' => $excerpt,  
  91. ), $post_data ); 
  92.  
  93. // This should never be set as it would then overwrite an existing attachment. 
  94. unset( $attachment['ID'] ); 
  95.  
  96. // Save the data 
  97. $id = wp_insert_attachment($attachment, $file, $post_id); 
  98. if ( !is_wp_error($id) ) { 
  99.  
  100. return $id; 
  101.