wp_handle_upload() │ WP 2.0.0

Processes file upload via $_FILES. Checks the file and moves it to the UPLOADS folder.

Before processing the file, the function checks and prepares the uploaded file:

cleans the file name and makes it unique if necessary.
checks the file extension (based on mime type).
saves the file in the corresponding directory /wp-content/uploads/.

The function works directly with the array $_FILES - this is not always convenient. Sometimes it is more convenient to specify the file data in an array and process it, for this use media_handle_sideload().

See wp_handle_sideload() - an analog of this function, but it works with the provided file data, not with the `$_FILES array.

Works based on the PHP function move_uploaded_file().

Uses: _wp_handle_upload()

Used By: media_handle_upload()

No Hooks.

Returns

Array.

On successful upload, returns an associative array of data in the following format:

Array
(
	[file] => sites/example.com/www/wp-content/uploads/2014/06/Daft-Punk-Something-About-Us.mp3
	[url] => http://example.com/wp-content/uploads/2014/06/Daft-Punk-Something-About-Us.mp3
	[type] => audio/mpeg
)

type and file can be used in the function wp_insert_attachment().

On failure, returns:

$overrides[upload_error_handler]() - the result of calling the function when the upload_error_handler parameter is specified, which indicates the error handling function.
array( 'error'=>$message ) - by default, when no error handling function is specified.

Usage

$movefile = wp_handle_upload( $file, $overrides, $time );

& $file(array) (required)

The element of the array $_FILES that contains an array of data about the accepted file (name, type, size, temporary location).

The parameter is passed by reference (&$file), so you need to pass the variable.

Array (
	[name]     => MyFile.txt         // taken from the browser form, so do not trust
	[type]     => text/plain         // file type. Taken from somewhere in the browser - do not trust
	[tmp_name] => /tmp/php/php1h4j1o // the file itself - file data in the file. Can be trusted
	[error]    => UPLOAD_ERR_OK      // = 0
	[size]     => 123                // file size in bytes - 1 KB = 1024 Bytes
)

$overrides(array)

An associative array of name => value, allows changing the default variables used in the function (variables are extracted like this: extract( $overrides, EXTR_OVERWRITE )).

For a real file upload, it is essential to specify the parameter 'test_form' => FALSE, otherwise, it will just be testing the form's functionality.

Possible parameters:

upload_error_handler(string) — the name of the error handling function. By default wp_handle_upload_error. The function receives two parameters &$file and $file['error']
unique_filename_callback(string) — your own function for making the file name unique. By default: null.
Testing parameters:
- test_form(true/false) — By default: true.
- test_size(true/false) — By default: true.
- test_type(true/false) — when overriding, you need to specify $ext and $type. By default: true.
- mimes(true/false) — when overriding, you need to specify $ext and $type. By default: false.

By default: false

$time(string)

Time in the format yyyy/mm, used to create the path to the folder where the file will be uploaded - folders in uploads. Passed to wp_upload_dir() to overwrite the default upload folder.
By default: null

Examples

#1 Downloading a file (Example of using the function)

Shows how to upload a file to the WP "uploads" directory, which is passed in the form. Let our form look like this:

<form enctype="multipart/form-data" action="" method="POST">
	<?php wp_nonce_field( 'my_file_upload', 'fileup_nonce' ); ?>
	<input name="my_file_upload" type="file" />
	<input type="submit" value="Upload file" />
</form>

The attribute enctype="multipart/form-data" is required for the form to handle files. Otherwise the field type="file" simply will not pass anything to $_FILES.

Then the code for loading the file will be as follows:

if( wp_verify_nonce( $_POST['fileup_nonce'], 'my_file_upload' ) ){

	if ( ! function_exists( 'wp_handle_upload' ) ) {
		require_once ABSPATH . 'wp-admin/includes/file.php';
	}

	$file = & $_FILES['my_file_upload'];

	$overrides = [ 'test_form' => false ];

	$movefile = wp_handle_upload( $file, $overrides );

	if ( $movefile && empty( $movefile['error'] ) ) {
		echo "The file was successfully uploaded.";
		print_r( $movefile );
	}
	else {
		echo $movefile['error'];
	}
}

Or for multiple file upload.

$files = & $_FILES['my_file_upload'];

foreach ( $files['name'] as $key => $value ) {

	if( empty( $files['name'][ $key ] ) ){
		continue;
	}

	$file = array(
		'name'     => $files['name'][ $key ],
		'type'     => $files['type'][ $key ],
		'tmp_name' => $files['tmp_name'][ $key ],
		'error'    => $files['error'][ $key ],
		'size'     => $files['size'][ $key ],
	);

	$movefile = wp_handle_upload( $file, [ 'test_form' => false ] );

	if( $movefile && empty( $movefile['error'] ) ){
		echo "The file was successfully uploaded.";
		print_r( $movefile );
	}
	else {
		echo $movefile['error'];
	}

}

Notes

See: _wp_handle_upload()

Changelog

Since 2.0.0

Introduced.

`wp_handle_upload() wp handle upload` code ^{WP 6.9.1}

wp-admin/includes/file.php

function wp_handle_upload( &$file, $overrides = false, $time = null ) {
	/*
	 *  $_POST['action'] must be set and its value must equal $overrides['action']
	 *  or this:
	 */
	$action = 'wp_handle_upload';
	if ( isset( $overrides['action'] ) ) {
		$action = $overrides['action'];
	}

	return _wp_handle_upload( $file, $overrides, $time, $action );
}