Функция wp_handle_sideload() в WordPress используется для обработки файлов, загруженных не через стандартный механизм загрузки файлов формы (как массив $_FILES), а, например, скачанных с удалённого сервера. Фактически, она служит обёрткой для более низкоуровневой функции _wp_handle_upload(), с некоторыми дополнительными возможностями.
wp_handle_sideload( array $file, array|false $overrides = false, string|null $time = null ): arrayПараметры
- $file (массив) — Обязательный параметр. Массив, аналогичный элементу из
$_FILES, содержащий информацию о загружаемом файле: имя, тип, временное местоположение, размер и возможные ошибки. - $overrides(массив|false) — Массив, позволяющий переопределить стандартные проверки загрузки, такие как:
test_form(bool) — по умолчаниюtrue, используется для проверки, была ли форма загрузки отправлена через браузер.test_size(bool) — по умолчаниюtrue, проверяет размер файла.test_upload(bool) — проверка правильности загрузки файла.
- $time (строка|null) — Опциональный параметр, используемый для создания пути в формате
yyyy/mmдля сохранения файла в соответствующую папку. По умолчанию равенnull, что означает текущий месяц.
Функция выполняет следующие задачи:
- Проверяет загружаемый файл на соответствие правилам безопасности (расширения, типы и т. д.).
- Перемещает файл из временного хранилища в целевую папку (обычно это директория
wp-content/uploads). - Возвращает массив с данными о загруженном файле, такими как путь до файла, его URL и MIME-тип.
Пример использования:
// Подключаем функции: download_url() и wp_handle_sideload()
require_once( ABSPATH . 'wp-admin/includes/file.php' );
// URL на файл для загрузки
$url = 'https://example.com/images/sample.png';
$timeout_seconds = 5;
// Загружаем файл во временную папку
$temp_file = download_url( $url, $timeout_seconds );
if ( ! is_wp_error( $temp_file ) ) {
// Формируем массив данных файла, как в $_FILES
$file = array(
'name' => basename($url), // Имя файла: sample.png
'type' => 'image/png',
'tmp_name' => $temp_file,
'error' => 0,
'size' => filesize( $temp_file ),
);
// Переопределения стандартных проверок
$overrides = array(
'test_form' => false, // Форма не требуется
'test_size' => true, // Проверка размера файла
'test_upload' => true, // Проверка корректности загрузки
);
// Обрабатываем загрузку файла
$results = wp_handle_sideload( $file, $overrides );
if ( ! empty( $results['error'] ) ) {
echo 'Ошибка загрузки: ' . $results['error'];
} else {
echo 'Файл успешно загружен: ' . $results['url'];
}
}
Пример: Использование с классом для уникализации имени файла
Если вам нужно уникализировать имена файлов при загрузке, можно задать собственную функцию уникализации через параметр unique_filename_callback.
class CustomUploader {
public function handle_custom_upload() {
// Подготавливаем данные для загрузки
$file = array(
'name' => 'custom-image.png',
'type' => 'image/png',
'tmp_name' => '/tmp/phpYzdqkD',
'error' => 0,
'size' => 512000,
);
$overrides = array(
'test_form' => false,
'unique_filename_callback' => array( $this, 'rename_file' )
);
$results = wp_handle_sideload( $file, $overrides );
if ( empty( $results['error'] ) ) {
echo 'Файл был загружен как: ' . $results['file'];
} else {
echo 'Ошибка загрузки: ' . $results['error'];
}
}
// Функция для уникализации имени файла
public static function rename_file( $dir, $name, $ext ) {
return 'custom_prefix_' . time() . '_' . $name . $ext;
}
}
// Используем класс для загрузки файла
$uploader = new CustomUploader();
$uploader->handle_custom_upload();
Возвращаемые значения
При успешной загрузке функция возвращает массив, содержащий:
url— Полный URL до файла в директории uploads.file— Полный путь на сервере до файла.type— MIME-тип файла.
Пример успешного результата:
Array
(
[file] => /home/user/example.com/wp-content/uploads/2024/10/sample.png
[url] => https://example.com/wp-content/uploads/2024/10/sample.png
[type] => image/png
)
При неудачной загрузке функция возвращает массив с ключом error, содержащий сообщение об ошибке:
Array
(
[error] => Ошибка загрузки файла
)
Заключение
Функция wp_handle_sideload() является полезным инструментом для перемещения файлов, загруженных нестандартными способами (например, через скачивание с удалённых серверов). Она позволяет гибко обрабатывать файлы, а также предоставляет возможности для кастомизации проверок и уникализации имён файлов.