WordPress.org

Languages: English • 日本語 (Add your language)

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 as
		// we downloaded the file from a remote server, so there
		// will be no form fields
		// Default is true
		'test_form' => false,

		// Setting this to false lets WordPress allow empty files, not recommended
		// Default is true
		'test_size' => 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()