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

Description

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

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.

Hooks fired · 4

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

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

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

2. 2
   apply_filters( {$action}_overrides )filterline 861 (+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 1012 (+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 1068 (+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

View on Trac ↗View on GitHub ↗

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

History

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