_wp_handle_upload( array $file, array|false $overrides, string $time, string $action ): array

Description

Compatibility

Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.

Parameters

$filearray

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

• $namestring

  The original name of the file on the client machine.

• $typestring

  The mime type of the file, if the browser provided this information.

• $tmp_namestring

  The temporary filename of the file in which the uploaded file was stored on the server.

• $sizeint

  The size, in bytes, of the uploaded file.

• $errorint

  The error code associated with this file upload.

$overridesarray|false

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

• $upload_error_handlercallable

  Function to call when there is an error during the upload process. See wp_handle_upload_error().

• $unique_filename_callbackcallable

  Function to call when determining a unique file name for the file. See wp_unique_filename().

• $upload_error_stringsstring[]

  The strings that describe the error indicated in $_FILES[{form field}]['error'].

• $test_formbool

  Whether to test that the $_POST['action'] parameter is as expected.

• $test_sizebool

  Whether to test that the file size is greater than zero bytes.

• $test_typebool

  Whether to test that the mime type of the file is as expected.

• $mimesstring[]

  Array of allowed mime types keyed by their file extension regex.

$timestring

Time formatted in 'yyyy/mm'.

$actionstring

Expected value for $_POST['action'].

Return value

array

On success, returns an associative array of file attributes. On failure, returns $overrides['upload_error_handler']( &$file, $message ) or array( 'error' => $message ).

• $filestring

  Filename of the newly-uploaded file.

• $urlstring

  URL of the newly-uploaded file.

• $typestring

  Mime type of the newly-uploaded file.

Performance profile

How much work a call to _wp_handle_upload() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.

Cost class

Heavy

Reads or writes the filesystem via filesize().

Scaling

Constant

No loop in the body: the same number of instructions runs whatever you pass in.

Instructions

121–228

Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 386.

Plugin surface

4 hooks

Third-party callbacks on '{$action}_prefilter', '{$action}_overrides', 'pre_move_uploaded_file' run inside this call, and their cost is not bounded by anything here.

Called by

2

2 places in core call this, so the cost is paid more often than your own code shows.

What it touches

• hookthird-party callbacksapply_filters()called directly
• filesystemfilesystem accessfilesize()called directly
• transienttransientget_transient()one call below _wp_handle_upload()

Further down the call graph this can also reach option, cache, query and serialize. Those are the worst case, several calls deep and usually down an error path, not what a normal call pays.

What one call costs · 70 distinct outcomes

One number would be a lie: the work depends on which branch runs. These are every distinct cost _wp_handle_upload() can have, taken from its control-flow graph on PHP 8.5.

This body has more branch combinations than are worth enumerating, so the table covers the outcomes found first rather than every one that exists.

Hooks and filters fired · 4

4 hooks fire while _wp_handle_upload() runs, in this order:

1. 1
   apply_filters( {$action}_prefilter )filterline 833 (+31 into the body)

   Filters the data for a file before it is uploaded to WordPress.

2. 2
   apply_filters( {$action}_overrides )filterline 859 (+57 into the body)

   Filters the override parameters for a file before it is uploaded to WordPress.

3. 3
   apply_filters( pre_move_uploaded_file )filterline 1010 (+208 into the body)

   Filters whether to short-circuit moving the uploaded file after passing all checks.

4. 4
   apply_filters( wp_handle_upload )filterline 1066 (+264 into the body)

   Filters the data array for the uploaded file.

Uses · 9

• apply_filters()Calls the callback functions that have been added to a filter hook.
• __()Retrieves the translation of $text.
• is_multisite()Determines whether Multisite is enabled.
• wp_check_filetype_and_ext()Attempts to determine the real file type of a file.
• current_user_can()Returns whether the current user has the specified capability.
• wp_upload_dir()Returns an array containing the current upload directory's path and URL.
• wp_unique_filename()Gets a filename that is sanitized and unique for the given directory.
• str_starts_with()Polyfill for `str_starts_with()` function added in PHP 8.0.
• clean_dirsize_cache()Cleans directory size cache used by recurse_dirsize().

Used by · 2

• wp_handle_sideload()Wrapper for _wp_handle_upload().
• wp_handle_upload()Wrapper for _wp_handle_upload().

Source code

View on Trac ↗View on GitHub ↗

802function _wp_handle_upload( &$file, $overrides, $time, $action ) {803	// The default error handler.804	if ( ! function_exists( 'wp_handle_upload_error' ) ) {805		function wp_handle_upload_error( &$file, $message ) {806			return array( 'error' => $message );807		}808	}809 810	/**811	 * Filters the data for a file before it is uploaded to WordPress.812	 *813	 * The dynamic portion of the hook name, `$action`, refers to the post action.814	 *815	 * Possible hook names include:816	 *817	 *  - `wp_handle_sideload_prefilter`818	 *  - `wp_handle_upload_prefilter`819	 *820	 * @since 2.9.0 as 'wp_handle_upload_prefilter'.821	 * @since 4.0.0 Converted to a dynamic hook with `$action`.822	 *823	 * @param array $file {824	 *     Reference to a single element from `$_FILES`.825	 *826	 *     @type string $name     The original name of the file on the client machine.827	 *     @type string $type     The mime type of the file, if the browser provided this information.828	 *     @type string $tmp_name The temporary filename of the file in which the uploaded file was stored on the server.829	 *     @type int    $size     The size, in bytes, of the uploaded file.830	 *     @type int    $error    The error code associated with this file upload.831	 * }832	 */833	$file = apply_filters( "{$action}_prefilter", $file );834 835	/**836	 * Filters the override parameters for a file before it is uploaded to WordPress.837	 *838	 * The dynamic portion of the hook name, `$action`, refers to the post action.839	 *840	 * Possible hook names include:841	 *842	 *  - `wp_handle_sideload_overrides`843	 *  - `wp_handle_upload_overrides`844	 *845	 * @since 5.7.0846	 *847	 * @param array|false $overrides An array of override parameters for this file. Boolean false if none are848	 *                               provided. See {@see _wp_handle_upload()}.849	 * @param array       $file      {850	 *     Reference to a single element from `$_FILES`.851	 *852	 *     @type string $name     The original name of the file on the client machine.853	 *     @type string $type     The mime type of the file, if the browser provided this information.854	 *     @type string $tmp_name The temporary filename of the file in which the uploaded file was stored on the server.855	 *     @type int    $size     The size, in bytes, of the uploaded file.856	 *     @type int    $error    The error code associated with this file upload.857	 * }858	 */859	$overrides = apply_filters( "{$action}_overrides", $overrides, $file );860 861	// You may define your own function and pass the name in $overrides['upload_error_handler'].862	$upload_error_handler = 'wp_handle_upload_error';863	if ( isset( $overrides['upload_error_handler'] ) ) {864		$upload_error_handler = $overrides['upload_error_handler'];865	}866 867	// You may have had one or more 'wp_handle_upload_prefilter' functions error out the file. Handle that gracefully.868	if ( isset( $file['error'] ) && ! is_numeric( $file['error'] ) && $file['error'] ) {869		return call_user_func_array( $upload_error_handler, array( &$file, $file['error'] ) );870	}871 872	// Install user overrides. Did we mention that this voids your warranty?873 874	// You may define your own function and pass the name in $overrides['unique_filename_callback'].875	$unique_filename_callback = null;876	if ( isset( $overrides['unique_filename_callback'] ) ) {877		$unique_filename_callback = $overrides['unique_filename_callback'];878	}879 880	/*881	 * This may not have originally been intended to be overridable,

Changelog

Introduced in 4.0.0. Unchanged from 6.7.7 through 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data

Generated from the wordpress-develop 6.9.7 tag, from src/wp-admin/includes/file.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.

Corrections

Something wrong on this page? Report it and it gets fixed in the next regeneration.