WordPress.org

Languages: English • 日本語 (Add your language)

Description

This function handles the file upload POST request itself, and creates the attachment post in the database.

Usage

<?php media_handle_upload( $file_id, $post_id, $post_data, $overrides ); ?>

Parameters

$file_id

(string) (required) Index into the $_FILES array of the upload

Default: None

$post_id

(int) (required) The post ID the media is associated with. If you don't want this media attached to a specific post, you can pass 0.

Default: None

$post_data

(array) (optional) allows you to overwrite some of the attachment

Default: array()

$overrides

(array) (optional) allows you to override the wp_handle_upload() behavior

Default: array( 'test_form' => false )

Return Values

(int|WP_Error) 

The ID of the attachment, or a WP_Error if the upload failed.

Examples

Upload an attachment from a form on the front end of the site.

The upload form might look like this:

<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>

The code to save the attachment:

<?php

// Check that the nonce is valid, and 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'] )
) {
	// The nonce was valid and the user has the capabilities, it is safe to continue.

	// These files need to be included as dependencies when on the 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' );
	
	// Let WordPress handle the upload.
	// Remember, 'my_image_upload' is the name of our file input in our form above.
	$attachment_id = media_handle_upload( 'my_image_upload', $_POST['post_id'] );
	
	if ( is_wp_error( $attachment_id ) ) {
		// There was an error uploading the image.
	} else {
		// The image was uploaded successfully!
	}

} else {

	// The security check failed, maybe show the user an error.
}

Change Log

Since: 2.5

Source File

media_handle_upload() is located in wp-admin/includes/media.php

Related

Upload Functions: media_handle_upload(), media_handle_sideload(), wp_handle_upload(), wp_import_handle_upload(), wp_handle_sideload(), media_sideload_image()

Attachment Functions:

get_children(), get attached media(), the_attachment_link(), get_attachment_link(), wp_get_attachment_link(), wp_get_attachment_image(), wp_get_attachment_image_src(), wp_get_attachment_url(), wp_get_attachment_thumb_file(), wp_get_attachment_thumb_url(), is_attachment(), wp_get_attachment_metadata()