media_handle_upload()
Uploads the file provided in the form to the WordPress uploads folder and creates a record of the file in the database (adds the file to the WP media library).
Works with the global variable $_FILES, the function needs to specify the index of the $_FILES array that contains data about the uploaded file, and the function will upload the file to the WordPress uploads folder and create a record of the attachment in the wp_posts table in the database. In the second parameter, you need to specify the ID of the post to which the uploaded media file should be attached.
To use this function on the front end, you need to include the 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';
When you need to work with arbitrary file data, rather than the bulk $_FILES, use media_handle_sideload().
No Hooks.
Returns
Int|WP_Error. ID of the created attachment. WP_error if the upload failed.
Usage
media_handle_upload( $file_id, $post_id, $post_data, $overrides );
- $file_id(string) (required)
- The index of the $_FILES array element that contains data about the accepted file (name, type, size, temporary location).
- $post_id(number) (required)
- The ID of the post to which the media file will be attached. If you do not want the file to be attached to a post, specify 0 in the parameter.
- $post_data(array)
- Allows you to overwrite the data of the created attachment. Here you specify the data that will be written to the wp_posts table for the created attachment: post_parent, post_title, post_excerpt, etc.
Default: array() (default data) - $overrides(array)
- Allows you to change the behavior of the wp_handle_upload() function, on which the current function is based.
Default: array( 'test_form' => false )
Examples
#1 Upload and save attachment file using custom HTML form
First, here's an HTML form example with a file upload field. Presumably the code is installed in the front end of the site:
<form id="featured_upload" method="post" action="#" enctype="multipart/form-data"> <input type="file" name="my_image_upload" id="my_image_upload" multiple="false" /> <input type="hidden" name="post_id" id="post_id" value="55" /> <?php wp_nonce_field( 'my_image_upload', 'my_image_upload_nonce' ); ?> <input id="submit_my_image_upload" name="submit_my_image_upload" type="submit" value="Upload" /> </form>
Make sure you use the enctype="multipart/form-data" attribute for the form.
If you don't, $_FILES will be empty and media_handle_upload() will return an error.
Now, handle the form submission and save the attachment file:
// Check the nonce protection and that the user can edit this post.
if (
isset( $_POST['my_image_upload_nonce'], $_POST['post_id'] )
&& wp_verify_nonce( $_POST['my_image_upload_nonce'], 'my_image_upload' )
&& current_user_can( 'edit_post', $_POST['post_id'] )
) {
// all ok! Moving on.
// These files must be connected in the front end (front-end).
require_once ABSPATH . 'wp-admin/includes/image.php';
require_once ABSPATH . 'wp-admin/includes/file.php';
require_once ABSPATH . 'wp-admin/includes/media.php';
// Catch the download using WordPress native function.
// Don't forget to specify the name attribute of the input field - 'my_image_upload'
$attachment_id = media_handle_upload( 'my_image_upload', $_POST['post_id'] );
if ( is_wp_error( $attachment_id ) ) {
echo 'Error loading media file';
} else {
echo 'The media file was successfully uploaded!';
}
}
else {
echo 'Check failed. Unable to download file.';
}
#2 Creating multiple file uploads in WordPress
WordPress allows you to upload multiple files at once, even with drag-and-drop capability, in the Admin panel. If you need to add such a feature on the front part of the site, it is not so difficult. To do this, let's create a page template (my-upload-page.php) and place the following form there:
<form action="" method="post" enctype="multipart/form-data" name="front_end_upload" > <label> Add all files here: <input type="file" name="kv_multiple_attachments[]" multiple="multiple"> </label> <input type="submit" name="Upload" > </form>
This form sends data to its own page (action=""), so in the code of the same file (my-upload-page.php) of the template you need to place a handler, see the example above.
Changelog
| Since 2.5.0 | Introduced. |