Title: wp_handle_upload
Published: April 25, 2014
Last modified: April 28, 2025

---

# wp_handle_upload( array $file, array|false $overrides = false, string|null $time = null ): array

## In this article

 * [Description](https://developer.wordpress.org/reference/functions/wp_handle_upload/?output_format=md#description)
    - [See also](https://developer.wordpress.org/reference/functions/wp_handle_upload/?output_format=md#see-also)
 * [Parameters](https://developer.wordpress.org/reference/functions/wp_handle_upload/?output_format=md#parameters)
 * [Return](https://developer.wordpress.org/reference/functions/wp_handle_upload/?output_format=md#return)
 * [Source](https://developer.wordpress.org/reference/functions/wp_handle_upload/?output_format=md#source)
 * [Related](https://developer.wordpress.org/reference/functions/wp_handle_upload/?output_format=md#related)
 * [Changelog](https://developer.wordpress.org/reference/functions/wp_handle_upload/?output_format=md#changelog)
 * [User Contributed Notes](https://developer.wordpress.org/reference/functions/wp_handle_upload/?output_format=md#user-contributed-notes)

[ Back to top](https://developer.wordpress.org/reference/functions/wp_handle_upload/?output_format=md#wp--skip-link--target)

Wrapper for [_wp_handle_upload()](https://developer.wordpress.org/reference/functions/_wp_handle_upload/).

## 󠀁[Description](https://developer.wordpress.org/reference/functions/wp_handle_upload/?output_format=md#description)󠁿

Passes the [‘wp_handle_upload’](https://developer.wordpress.org/reference/hooks/wp_handle_upload/)
action.

### 󠀁[See also](https://developer.wordpress.org/reference/functions/wp_handle_upload/?output_format=md#see-also)󠁿

 * [_wp_handle_upload()](https://developer.wordpress.org/reference/functions/_wp_handle_upload/)

## 󠀁[Parameters](https://developer.wordpress.org/reference/functions/wp_handle_upload/?output_format=md#parameters)󠁿

 `$file`arrayrequired

Reference to a single element of `$_FILES`.
 Call the function once for each uploaded
file. See [_wp_handle_upload()](https://developer.wordpress.org/reference/functions/_wp_handle_upload/)
for accepted values.

More Arguments from _wp_handle_upload( … $file )

Reference to a single element from `$_FILES`. Call the function once for each uploaded
file.

 * `name` string
 * The original name of the file on the client machine.
 * `type` string
 * The mime type of the file, if the browser provided this information.
 * `tmp_name` string
 * The temporary filename of the file in which the uploaded file was stored on the
   server.
 * `size` int
 * The size, in bytes, of the uploaded file.
 * `error` int
 * The error code associated with this file upload.

`$overrides`array|falseoptional

An associative array of names => values to override default variables. 
 See [_wp_handle_upload()](https://developer.wordpress.org/reference/functions/_wp_handle_upload/)
for accepted values.

More Arguments from _wp_handle_upload( … $overrides )

An array of override parameters for this file, or boolean false if none are provided.

 * `upload_error_handler` callable
 * Function to call when there is an error during the upload process.
    See [wp_handle_upload_error()](https://developer.wordpress.org/reference/functions/wp_handle_upload_error/).
 * `unique_filename_callback` callable
 * Function to call when determining a unique file name for the file.
    See [wp_unique_filename()](https://developer.wordpress.org/reference/functions/wp_unique_filename/).
 * `upload_error_strings` string[]
 * The strings that describe the error indicated in `$_FILES[{form field}]['error']`.
 * `test_form` bool
 * Whether to test that the `$_POST['action']` parameter is as expected.
 * `test_size` bool
 * Whether to test that the file size is greater than zero bytes.
 * `test_type` bool
 * Whether to test that the mime type of the file is as expected.
 * `mimes` string[]
 * Array of allowed mime types keyed by their file extension regex.

Default:`false`

`$time`string|nulloptional

Time formatted in `'yyyy/mm'`.

Default:`null`

## 󠀁[Return](https://developer.wordpress.org/reference/functions/wp_handle_upload/?output_format=md#return)󠁿

 array See [_wp_handle_upload()](https://developer.wordpress.org/reference/functions/_wp_handle_upload/)
for return value.

## 󠀁[Source](https://developer.wordpress.org/reference/functions/wp_handle_upload/?output_format=md#source)󠁿

    ```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 );
    }
    ```

[View all references](https://developer.wordpress.org/reference/files/wp-admin/includes/file.php/)
[View on Trac](https://core.trac.wordpress.org/browser/tags/6.9.4/src/wp-admin/includes/file.php#L1095)
[View on GitHub](https://github.com/WordPress/wordpress-develop/blob/6.9.4/src/wp-admin/includes/file.php#L1095-L1106)

## 󠀁[Related](https://developer.wordpress.org/reference/functions/wp_handle_upload/?output_format=md#related)󠁿

| Uses | Description | 
| [_wp_handle_upload()](https://developer.wordpress.org/reference/functions/_wp_handle_upload/)`wp-admin/includes/file.php` |

Handles PHP uploads in WordPress.

  |

| Used by | Description | 
| [WP_REST_Font_Faces_Controller::handle_font_file_upload()](https://developer.wordpress.org/reference/classes/wp_rest_font_faces_controller/handle_font_file_upload/)`wp-includes/rest-api/endpoints/class-wp-rest-font-faces-controller.php` |

Handles the upload of a font file using [wp_handle_upload()](https://developer.wordpress.org/reference/functions/wp_handle_upload/) .

  | 
| [WP_REST_Attachments_Controller::upload_from_file()](https://developer.wordpress.org/reference/classes/wp_rest_attachments_controller/upload_from_file/)`wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php` |

Handles an upload via multipart/form-data ($_FILES).

  | 
| [File_Upload_Upgrader::__construct()](https://developer.wordpress.org/reference/classes/file_upload_upgrader/__construct/)`wp-admin/includes/class-file-upload-upgrader.php` |

Construct the upgrader for a form.

  | 
| [media_handle_upload()](https://developer.wordpress.org/reference/functions/media_handle_upload/)`wp-admin/includes/media.php` |

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

  | 
| [wp_import_handle_upload()](https://developer.wordpress.org/reference/functions/wp_import_handle_upload/)`wp-admin/includes/import.php` |

Handles importer uploading and adds attachment.

  | 
| [Custom_Image_Header::step_2_manage_upload()](https://developer.wordpress.org/reference/classes/custom_image_header/step_2_manage_upload/)`wp-admin/includes/class-custom-image-header.php` |

Uploads the file to be cropped in the second step.

  | 
| [Custom_Background::handle_upload()](https://developer.wordpress.org/reference/classes/custom_background/handle_upload/)`wp-admin/includes/class-custom-background.php` |

Handles an Image upload for the background image.

  |

[Show 2 more](https://developer.wordpress.org/reference/functions/wp_handle_upload/?output_format=md#)
[Show less](https://developer.wordpress.org/reference/functions/wp_handle_upload/?output_format=md#)

## 󠀁[Changelog](https://developer.wordpress.org/reference/functions/wp_handle_upload/?output_format=md#changelog)󠁿

| Version | Description | 
| [2.0.0](https://developer.wordpress.org/reference/since/2.0.0/) | Introduced. |

## 󠀁[User Contributed Notes](https://developer.wordpress.org/reference/functions/wp_handle_upload/?output_format=md#user-contributed-notes)󠁿

 1.   [Skip to note 3 content](https://developer.wordpress.org/reference/functions/wp_handle_upload/?output_format=md#comment-content-3806)
 2.    [Mohit Mishra](https://profiles.wordpress.org/mohitmishra/)  [  6 years ago  ](https://developer.wordpress.org/reference/functions/wp_handle_upload/#comment-3806)
 3.  [You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_handle_upload%2F%23comment-3806)
     Vote results for this note: 4[You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_handle_upload%2F%23comment-3806)
 4.      ```php
         if ( ! function_exists( 'wp_handle_upload' ) ) {
         	require_once( ABSPATH . 'wp-admin/includes/file.php' );
         }
         // for multiple file upload.
         $upload_overrides = array( 'test_form' => false );
         $files = $_FILES['file'];
         foreach ( $files['name'] as $key => $value ) {
         	if ( $files['name'][ $key ] ) {
         		$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, $upload_overrides );
         	}
         }
         }
         ```
     
 5.   [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_handle_upload%2F%3Freplytocom%3D3806%23feedback-editor-3806)
 6.   [Skip to note 4 content](https://developer.wordpress.org/reference/functions/wp_handle_upload/?output_format=md#comment-content-1294)
 7.    [Codex](https://profiles.wordpress.org/codex/)  [  10 years ago  ](https://developer.wordpress.org/reference/functions/wp_handle_upload/#comment-1294)
 8.  [You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_handle_upload%2F%23comment-1294)
     Vote results for this note: 3[You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_handle_upload%2F%23comment-1294)
 9.  **Example**
 10.     ```php
         if ( ! function_exists( 'wp_handle_upload' ) ) {
             require_once( ABSPATH . 'wp-admin/includes/file.php' );
         }
     
         $uploadedfile = $_FILES['file'];
     
         $upload_overrides = array(
         	'test_form' => false
         );
     
         $movefile = wp_handle_upload( $uploadedfile, $upload_overrides );
     
         if ( $movefile && ! isset( $movefile['error'] ) ) {
             echo __( 'File is valid, and was successfully uploaded.', 'textdomain' ) . "\n";
             var_dump( $movefile );
         } else {
             /*
              * Error generated by _wp_handle_upload()
              * @see _wp_handle_upload() in wp-admin/includes/file.php
              */
             echo $movefile['error'];
         }
         ```
     
 11.  [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_handle_upload%2F%3Freplytocom%3D1294%23feedback-editor-1294)

You must [log in](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_handle_upload%2F)
before being able to contribute a note or feedback.