wp_handle_sideload() │ WP 2.6.0

Moves a temporary file to the uploads folder.

Specifies the action name: wp_handle_sideload. The action can be changed in the $overrides['action'] variable.

This function is based on _wp_handle_upload(). It handles PHP file upload: cleans the file name(s), checks the extension for mime types, saves (moves) the file to the appropriate folder in the uploads directory.

To use the function outside the admin area you need to include the file:

// include the functions we need: download_url() and wp_handle_sideload()
require_once ABSPATH . 'wp-admin/includes/file.php';

See wp_handle_upload() — an equivalent of this function that works with the $_FILES array, rather than passed file data.

Uses: _wp_handle_upload()
Used By: media_handle_sideload()

No Hooks.

Returns

Array.

  • Array of uploaded file parameters.

    array(
	'url' => 'https://example.com/wp-content/uploads/2022/05/file-name.png',
	'file' => '/home/user/example.com/wp-content/uploads/2022/05/file-name.png',
	'type' => 'image/png',
)
  • On failure it will return the value of $overrides['upload_error_handler'] or an array [ 'error' => $message ].

Usage

wp_handle_sideload( $file, $overrides, $time );
$file(array) (required)

Array of file data - analogous to the PHP $_FILES array that is passed in a POST request.

Array (
	[name]     => MyFile.txt         // comes from the browser form, so do not trust
	[type]     => text/plain         // file type. Comes from somewhere in the browser - do not trust
	[tmp_name] => /tmp/php/php1h4j1o // the file itself - the file's data on disk. Can be trusted
	[error]    => UPLOAD_ERR_OK      // = 0
	[size]     => 123                // file size in bytes - 1 KB = 1024 Bytes
)
$overrides(array/boolean)

An associative array of name => value, allows overriding default parameters. Possible parameters:

  • upload_error_handler(string) — a custom error handling function. Default: 'wp_handle_upload_error'.
  • unique_filename_callback(string) — a custom function for making unique file names. Default: null.
  • test_form(true/false) — Default: true.
  • test_size(true/false) — Default: true.
  • test_type(true/false) — when overriding you need to specify $ext and $type. Default: true.
  • mimes(true/false) — when overriding you need to specify $ext and $type. Default: false.

Default: false

$time(string)
Time in format yyyy/mm, used to build the path for the uploads folder — where the file will be uploaded. Passed to wp_upload_dir() to override the default upload folder.
Default: null

Examples

0

#1 Upload a remote file (from another site) to the current site uploads folder.

This example uses download_url() to download the specified file and then move it to the uploads directory.

// In the front-end, the following file is needed to have ability to use
// 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;

// upload the file to a temporary folder
$temp_file = download_url( $url, $timeout_seconds );

if( ! is_wp_error( $temp_file ) ){

	// assemble an array similar to $_FILE in PHP
	$file = array(
		'name'     => basename( $url ), // get: 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,
	);

	// move the temporary file to the uploads folder
	$results = wp_handle_sideload( $file, $overrides );

	if( ! empty($results['error']) ){
		// add an error handler here
	}
	else {

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

		// do something based on the data
	}

}
0

#2 Rename uploaded file (use PHP Class)

If you want to rename your uploaded file and you use a PHP class it is needed to do the callback like this:

class My_Class {

	public function my_custom_upload() {

		// Getting file information
		$file = isset( $_FILES ) ? $_FILES : array();

		// For exemple it is an image
		$allowed_mimes = array(
			'jpg|jpeg|jpe'  => 'image/jpeg',
			'gif'           => 'image/gif',
			'png'           => 'image/png',
		);

		$uploaded_file = wp_handle_sideload( $file['image'], array(
				'test_form' => false,
				'mimes'     => $allowed_mimes,
				'unique_filename_callback' => array( $this, 'rename_uploaded_file' ),
			)
		);
	}

	public static function rename_uploaded_file( $dir, $name, $ext ) {
		return 'some_string' . $name . $ext;
	}

}

Notes

Changelog

Since 2.6.0 Introduced.

wp_handle_sideload() code WP 7.0

wp-admin/includes/file.php 
function wp_handle_sideload( &$file, $overrides = false, $time = null ) {
	/*
	 *  $_POST['action'] must be set and its value must equal $overrides['action']
	 *  or this:
	 */
	$action = $overrides['action'] ?? 'wp_handle_sideload';
	return _wp_handle_upload( $file, $overrides, $time, $action );
}

upload download (file system)