wp_handle_upload()

💡 云策文档标注

概述

wp_handle_upload() 是 WordPress 中处理文件上传的核心函数，作为 _wp_handle_upload() 的包装器，简化了上传流程。它接收 $_FILES 数组元素和可选覆盖参数，返回上传结果数组，常用于媒体处理、REST API 和自定义上传场景。

关键要点

函数是 _wp_handle_upload() 的包装器，触发 'wp_handle_upload' action
参数 $file 必须引用 $_FILES 的单个元素，每个文件需单独调用
参数 $overrides 可选，用于覆盖默认设置如 test_form、mimes 等
返回数组包含上传文件信息，错误时返回错误详情
常用于媒体上传、REST API 控制器和自定义上传处理

代码示例

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 {
    echo $movefile['error'];
}

注意事项

确保 $_FILES 数组元素正确，避免上传错误
使用 $overrides 参数可自定义上传行为，如禁用表单测试
处理多文件上传时需循环调用函数
错误处理应检查返回数组中的 'error' 键

📄 原文内容

Wrapper for _wp_handle_upload() .

Description

Passes the ‘wp_handle_upload’ action.

Parameters

$filearrayrequired

Reference to a single element of $_FILES.
Call the function once for each uploaded file.
See _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.

$overridesarray|falseoptional

An associative array of names => values to override default variables.
See _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().
unique_filename_callback callable
Function to call when determining a unique file name for the file.
See 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

$timestring|nulloptional

Time formatted in 'yyyy/mm'.

Default:null

Return

array See _wp_handle_upload() for return value.

Source

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 View on Trac View on GitHub

Uses	Description
_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()`wp-includes/rest-api/endpoints/class-wp-rest-font-faces-controller.php`	Handles the upload of a font file using wp_handle_upload() .
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()`wp-admin/includes/class-file-upload-upgrader.php`	Construct the upgrader for a form.
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()`wp-admin/includes/import.php`	Handles importer uploading and adds attachment.
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()`wp-admin/includes/class-custom-background.php`	Handles an Image upload for the background image.

Show 2 more Show less

Changelog

Version	Description
2.0.0	Introduced.

User Contributed Notes

Skip to note 3 content

Mohit Mishra

6 years ago

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

Skip to note 4 content

Codex

10 years ago

Example

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'];
}

云策 WordPress 开发者社区

函数文档