Handle sideloads, which is the process of retrieving a media item from another server instead of a traditional media upload. This process involves sanitizing the filename, checking extensions for mime type, and moving the file to the appropriate directory within the uploads directory.

wp_handle_sideload() 描述


<?php wp_handle_sideload( &$file$overrides$time ); ?>

wp_handle_sideload() 用法



(array) (必填) an array similar to that of a PHP $_FILES POST array

默认值: None


(array) (可选) An associative array of names => values to override default variables with extract( $overrides, EXTR_OVERWRITE ).

默认值: false


(string) (可选) Time formatted in 'yyyy/mm', gets passed to wp_upload_dir() to override the default upload directory.

默认值: null

wp_handle_sideload() 参数



On success, returns an associative array of file attributes. On failure, returns the return of the upload error handler, which by default would be array( 'error' => $message ).

wp_handle_sideload() 返回值


This example uses download_url() to download the logo from wordpress.org and then moves it into the uploads directory.

/* ----------------------------------
 * wordpress之魂 © http://wphun.com
 * ---------------------------------- */

// gives us access to the download_url() and wp_handle_sideload() functions
require_once(ABSPATH . 'wp-admin/includes/file.php');

// URL to the WordPress logo
$url = 'http://s.w.org/style/images/wp-header-logo.png';
$timeout_seconds = 5;

// download file to temp dir
$temp_file = download_url( $url, $timeout_seconds );

if (!is_wp_error( $temp_file )) {

	// array based on $_FILE as seen in PHP file uploads
	$file = array(
		'name' => basename($url), // ex: wp-header-logo.png
		'type' => 'image/png',
		'tmp_name' => $temp_file,
		'error' => 0,
		'size' => filesize($temp_file),

	$overrides = array(
		// tells WordPress to not look for the POST form
		// fields that would normally be present, default is true,
		// we downloaded the file from a remote server, so there
		// will be no form fields
		'test_form' => false,

		// setting this to false lets WordPress allow empty files, not recommended
		'test_size' => true,

		// A properly uploaded file will pass this test. 
		// There should be no reason to override this one.
		'test_upload' => true, 

	// move the temporary file into the uploads directory
	$results = wp_handle_sideload( $file, $overrides );

	if (!empty($results['error'])) {
		// insert any error handling here
	} else {

		$filename = $results['file']; // full path to the file
		$local_url = $results['url']; // URL to the file in the uploads dir
		$type = $results['type']; // MIME type of the file

		// perform any actions here based in the above results


wp_handle_sideload() 示例


添加于 版本: 2.6.0

wp_handle_sideload() 历史


wp_handle_sideload() 函数的代码位于 wp-admin/includes/file.php

/* ----------------------------------
 * wordpress之魂 © http://wphun.com
 * ---------------------------------- */
 * Wrapper for _wp_handle_upload(), passes 'wp_handle_sideload' action
 * @since 2.6.0
 * @see _wp_handle_upload()
 * @param array      $file      An array similar to that of a PHP $_FILES POST array
 * @param array|bool $overrides Optional. An associative array of names=>values to override default
 *                              variables. Default false.
 * @param string     $time      Optional. Time formatted in 'yyyy/mm'. Default null.
 * @return array On success, returns an associative array of file attributes. On failure, returns
 *               $overrides['upload_error_handler'](&$file, $message ) or array( 'error'=>$message ).
function wp_handle_sideload( &$file, $overrides = false, $time = null ) {
	 *  $_POST['action'] must be set and its value must equal $overrides['action']
	 *  or this:
	$action = 'wp_handle_sideload';
	if ( isset( $overrides['action'] ) ) {
		$action = $overrides['action'];
	return _wp_handle_upload( $file, $overrides, $time, $action );

wp_handle_sideload() 源文件