wp_handle_upload() WP 2.0

Обрабатывает загрузку файла через $_FILES. Проверяет файл и перемещает его в папку UPLOADS.

Перед обработкой файла функция проверяет и подготавливает загружаемый файл:

• очищает название файла и уникализирует его если нужно.
• проверяет расширение файла (на основе mime типа).
• сохраняет файл в соответствующий каталог /wp-content/uploads/.

Хуков нет.

Возвращает

Массив.

При успешной загрузке возвращает ассоциативный массив данных, такого формата:

Array
(
	[file] => sites/wptest.ru/www/wp-content/uploads/2014/06/Daft-Punk-Something-About-Us.mp3
	[url] => http://wptest.ru/wp-content/uploads/2014/06/Daft-Punk-Something-About-Us.mp3
	[type] => audio/mpeg
)

При неудаче, возвращает:

• $overrides[upload_error_handler]() - результат вызова функции, когда указан параметр upload_error_handler, в котором указана функция обработки ошибки.

• array( 'error'=>$message ) - по умолчанию, когда не указана функция обработки ошибки.

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

$movefile = wp_handle_upload( $file, $overrides, $time );

& $file(массив) (обязательный)

Элемент массива $_FILES, который содержит массив данных о принятом файле (название, тип, размер, временное расположение).

Параметр передается по ссылке (&$file), поэтому нужно передавать переменную.

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

$overrides(массив)

Ассоциативный массив из name => value, позволяет изменить дефолтные переменные используемые в функции (переменные извлекаются так: extract( $overrides, EXTR_OVERWRITE )).

Чтобы произошла реальная загрузка файла обязательно нужно указать параметр 'test_form' => FALSE, в противном случае это будет просто тестирование работы формы.

Возможные параметры:

• upload_error_handler(строка) — название функции обработки ошибок. По умолчанию wp_handle_upload_error. Функция получает два параметра &$file и $file['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

Примеры

#1 Загрузка файла

Пример использования функции. Показывает как загрузить файл в каталог WP "uploads", который передается в форме. Пусть так выглядит наша форма:

<form enctype="multipart/form-data" action="" method="POST">
	<?php wp_nonce_field( 'my_file_upload', 'fileup_nonce' ); ?>
	<input name="my_file_upload" type="file" />
	<input type="submit" value="Загрузить файл" />
</form>

Тогда код загрузки файла будет такой:

if( wp_verify_nonce( $_POST['fileup_nonce'], 'my_file_upload' ) ){

	if ( ! function_exists( 'wp_handle_upload' ) )
		require_once( ABSPATH . 'wp-admin/includes/file.php' );

	$file = & $_FILES['my_file_upload'];

	$overrides = [ 'test_form' => false ];

	$movefile = wp_handle_upload( $file, $overrides );

	if ( $movefile && empty($movefile['error']) ) {
		echo "Файл был успешно загружен.\n";
		print_r( $movefile );
	} else {
		echo "Возможны атаки при загрузке файла!\n";
	}
}

Заметки

• Смотрите: _wp_handle_upload()

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

Код wp_handle_upload() wp handle upload ^{WP 5.8.3}

function wp_handle_upload( &$file, $overrides = false, $time = null ) {
	/*
	 *  $_POST['action'] must be set and its value must equal $overrides['action']
	 *  or this:
	 */
	$action = 'wp_handle_upload';
	if ( isset( $overrides['action'] ) ) {
		$action = $overrides['action'];
	}

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

Cвязанные функции

upload download (файловая система file загрузка)

Загрузка (download upload)