wp_handle_sideload() │ WP 2.6.0

Wrapper for _wp_handle_upload().

Passes the {@see 'wp_handle_sideload'} action.

Uses: _wp_handle_upload()

Used By: media_handle_sideload()

No Hooks.

Return

Array. See _wp_handle_upload() for return value.

Usage

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

$file(array) (required) (passed by reference — &): Reference to a single element of $_FILES. Call the function once for each uploaded file. See _wp_handle_upload() for accepted values.
$overrides(array|false): An associative array of names => values to override default variables. See _wp_handle_upload() for accepted values.
Default: false
$time(string|null): Time formatted in 'yyyy/mm'.
Default: null

Examples

#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
	}

}

#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

See: _wp_handle_upload()

Changelog

Since 2.6.0

Introduced.

`wp_handle_sideload() wp handle sideload` code ^{WP 6.6.2}

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 = 'wp_handle_sideload';
	if ( isset( $overrides['action'] ) ) {
		$action = $overrides['action'];
	}

	return _wp_handle_upload( $file, $overrides, $time, $action );
}