wp_handle_sideload( array $file, array|false $overrides = false, string $time = null )

Wrapper for _wp_handle_upload().

Contents

Description Description

Passes the ‘wp_handle_sideload’ action.

See also See also

Top ↑

Parameters Parameters

$file

(array) (Required) Reference to a single element of $_FILES. Call the function once for each uploaded file.

$overrides

(array|false) (Optional) An associative array of names => values to override default variables.

Default value: false

$time

(string) (Optional) Time formatted in 'yyyy/mm'.

Default value: null

Top ↑

Return Return

(array) On success, returns an associative array of file attributes. On failure, returns $overrides['upload_error_handler']( &$file, $message ) or array( 'error' => $message ).

Top ↑

Source Source

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

Expand full source code Collapse full source code View on Trac

Top ↑

Top ↑

Changelog Changelog

Changelog
Version Description
2.6.0 Introduced.

Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note 1 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    Example

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

    // 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 = 'https://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.
	}
}

    Expand full source codeCollapse full source code

  3. Skip to note 3 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note
    Contributed by Vladut Ilie —

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

    Expand full source codeCollapse full source code

You must log in before being able to contribute a note or feedback.