wp_handle_sideload()WP 2.6.0

Перемещает временный файл в папку uploads.

Указывает название события: wp_handle_sideload. Событие можно изменить в переменной $overrides['action'].

В основе этой функции лежит _wp_handle_upload(). Она обрабатывает PHP загрузку файла: очищает название файла(ов), проверяет расширение для mime типов, сохраняет (перемещает) файл в нужную папку в папке uploads.

Для работы функции не в админке нужно подключить файл:

// подключаем нужные нам функции: download_url() и wp_handle_sideload()
require_once ABSPATH . 'wp-admin/includes/file.php';

Смотрите wp_handle_upload() - аналог этой функции, только работает с массивом $_FILES, а не с переданными данными файла.

Работает на основе: _wp_handle_upload()
Основа для: media_handle_sideload()

Хуков нет.

Возвращает

Массив.

  • Массив с параметрами загруженного файла.

    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',
    )
  • При неудаче вернет значение $overrides['upload_error_handler'] или массив [ 'error' => $message ].

Использование

wp_handle_sideload( $file, $overrides, $time );
$file(массив) (обязательный)

Массив с данными файла - аналогичный PHP массиву $_FILES, который передается в POST запросе.

Array (
	[name]     => MyFile.txt         // берется из формы браузера, поэтому не доверяем
	[type]     => text/plain         // тип файла. Берется откуда-то из браузера - не доверяем
	[tmp_name] => /tmp/php/php1h4j1o // сам файл - данные файла в файле. Можно доверять
	[error]    => UPLOAD_ERR_OK      // = 0
	[size]     => 123                // размер файла в байтах - 1 КБ = 1024 Байт
)
$overrides(массив/логический)

Ассоциативный массив из name => value, позволяет изменить параметры по умолчанию. Возможные параметры:

  • upload_error_handler(строка) — своя функция обработки ошибок. По умолчанию: 'wp_handle_upload_error'.
  • unique_filename_callback(строка) — своя функция уникализации имени файла. По умолчанию: null.
  • test_form(true/false) — По умолчанию: true.
  • test_size(true/false) — По умолчанию: true.
  • test_type(true/false) — при переопределении нужно указать $ext и $type. По умолчанию: true.
  • mimes(true/false) — при переопределении нужно указать $ext и $type. По умолчанию: false.

По умолчанию: false

$time(строка)
Время в формате yyyy/mm, используется для построения пути для папки uploads - куда файл будет загружен. Передается в wp_upload_dir() чтобы переписать папку загрузки по умолчанию.
По умолчанию: null

Примеры

0

#1 Загрузка удаленного файла (с другого сервера) в папку uploads.

Этот пример использует download_url(), чтобы загрузить указанный файл, а затем переместить его в каталог uploads.

// во фронт-энде для работы функции нужен следующий файл: 'wp-admin/includes/file.php'
// подключаем нужные нам функции: download_url() и wp_handle_sideload()
require_once( ABSPATH . 'wp-admin/includes/file.php');

// URL на лого WordPress
$url = 'http://s.w.org/style/images/wp-header-logo.png';
$timeout_seconds = 5;

// загружаем файл во временную папку
$temp_file = download_url( $url, $timeout_seconds );

if( ! is_wp_error( $temp_file ) ){

	// соберем массив аналогичный $_FILE в PHP
	$file = array(
		'name'     => basename($url), // получит: wp-header-logo.png
		'type'     => 'image/png',
		'tmp_name' => $temp_file,
		'error'    => 0,
		'size'     => filesize($temp_file),
	);

	$overrides = array(
		// скажем WP не искать поля формы, которые обычно должны быть.
		// загружаем файл с удаленного сервера, поэтому полей формы нет.
		'test_form' => false,
	);

	// перемещаем временный файл в папку uploads
	$results = wp_handle_sideload( $file, $overrides );

	if( ! empty($results['error']) ){
		// Добавьте сюда обработчик ошибок
	}
	else {

		$filename = $results['file']; // полный путь до файла
		$local_url = $results['url']; // URL до файла в папке uploads
		$type = $results['type']; // MIME тип файла

		// делаем что-либо на основе полученных данных
	}

}

Заметки

Список изменений

С версии 2.6.0 Введена.

Код wp_handle_sideload() WP 6.4.3

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