WordPress.org

Ready to get started?Download WordPress

Codex

Attention Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Function Reference/wp handle sideload

This page is marked as incomplete. You can help Codex by expanding it.

Contents

Description

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.

Usage

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

Parameters

$file
(array) (required) an array similar to that of a PHP $_FILES POST array
Default: None
$overrides
(array) (optional) An associative array of names => values to override default variables with extract( $overrides, EXTR_OVERWRITE ).
Default: false
$time
(string) (optional) Time formatted in 'yyyy/mm', gets passed to wp_upload_dir() to override the default upload directory.
Default: null

Return Values

(array) 
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 ).

Examples

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 = '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
	}

}

Notes

Change Log

Since: 2.6.0

Source File

wp_handle_sideload() is located in wp-admin/includes/file.php

Related

Upload Functions: media_handle_upload(), media_handle_sideload(), wp_handle_upload(), wp_import_handle_upload(), wp_handle_sideload(), media_sideload_image()

See also index of Function Reference and index of Template Tags.