Функция wp_handle_upload() в WordPress используется для обработки загружаемых файлов, которые передаются через массив $_FILES. Она обеспечивает проверку и перемещение файлов в каталог загрузок WordPress, а также выполняет проверки на допустимые типы файлов и ошибки загрузки.
wp_handle_upload( array $file, array|false $overrides = false, string|null $time = null ): array
Параметры:
$file(обязательный): Массив, содержащий данные о файле из$_FILES, такие как имя, тип, временное расположение, ошибки и размер файла.$overrides(необязательный): Ассоциативный массив для переопределения стандартных параметров загрузки, таких как проверка формы, типы файлов, размер и т. д.$time(необязательный): Время в форматеyyyy/mm, указывающее на папку для сохранения файла (например,uploads/2024/10).
Возвращаемое значение:
Ассоциативный массив с информацией о загруженном файле:
file— полный путь к загруженному файлу.url— URL загруженного файла.type— MIME-тип файла.
При ошибке загрузки возвращается массив с ключом error и сообщением об ошибке.
Пример 1: Простая загрузка файла
Для обработки файла, загружаемого через форму, можно использовать следующий код:
if ( ! function_exists( 'wp_handle_upload' ) ) {
require_once( ABSPATH . 'wp-admin/includes/file.php' );
}
if ( isset( $_FILES['my_file'] ) ) {
$uploadedfile = $_FILES['my_file'];
$upload_overrides = array(
'test_form' => false, // Отключаем проверку формы.
);
$movefile = wp_handle_upload( $uploadedfile, $upload_overrides );
if ( $movefile && ! isset( $movefile['error'] ) ) {
echo "Файл успешно загружен: " . $movefile['url'];
} else {
echo "Ошибка загрузки файла: " . $movefile['error'];
}
}
В этом примере файл загружается из поля формы с именем my_file, и результат выводится в зависимости от успеха или ошибки загрузки.
Пример 2: Загрузка нескольких файлов
Если вам нужно обработать несколько файлов, переданных через массив $_FILES, можно использовать цикл:
if ( ! function_exists( 'wp_handle_upload' ) ) {
require_once( ABSPATH . 'wp-admin/includes/file.php' );
}
$files = $_FILES['my_files'];
$upload_overrides = array( 'test_form' => false ); // Отключаем проверку формы.
foreach ( $files['name'] as $key => $value ) {
if ( $files['name'][ $key ] ) {
$file = array(
'name' => $files['name'][ $key ],
'type' => $files['type'][ $key ],
'tmp_name' => $files['tmp_name'][ $key ],
'error' => $files['error'][ $key ],
'size' => $files['size'][ $key ],
);
$movefile = wp_handle_upload( $file, $upload_overrides );
if ( $movefile && ! isset( $movefile['error'] ) ) {
echo "Файл успешно загружен: " . $movefile['url'] . "<br />";
} else {
echo "Ошибка загрузки файла: " . $movefile['error'] . "<br />";
}
}
}
В этом примере мы обрабатываем массив файлов, переданных через форму, и выводим информацию о каждом из них.
Пример 3: Обработка ошибок
Если файл не может быть загружен (например, если размер файла превышает допустимый или его тип запрещен), функция вернет ошибку. Для этого можно задать пользовательскую функцию обработки ошибок через параметр upload_error_handler:
function my_custom_upload_error_handler( $file, $error ) {
return "Произошла ошибка при загрузке файла: $error";
}
$overrides = array(
'test_form' => false,
'upload_error_handler' => 'my_custom_upload_error_handler'
);
$movefile = wp_handle_upload( $_FILES['my_file'], $overrides );
if ( isset( $movefile['error'] ) ) {
echo $movefile['error'];
} else {
echo "Файл успешно загружен.";
}
Этот код покажет более подробное сообщение об ошибке загрузки.
Опции и параметры
test_form: По умолчанию проверяется, что файл загружен через форму. Если вы хотите отключить эту проверку, установитеtest_form => false.mimes: Позволяет ограничить типы файлов, допустимые к загрузке. Например, разрешить только изображения:
$overrides = array(
'test_form' => false,
'mimes' => array(
'jpg|jpeg|jpe' => 'image/jpeg',
'png' => 'image/png',
)
);
unique_filename_callback: Позволяет задать свою функцию для уникализации имени загружаемого файла.
Как работает wp_handle_upload()
Функция использует стандартные PHP-функции, такие как move_uploaded_file(), для перемещения файла из временного каталога в постоянный каталог загрузок WordPress (обычно это /wp-content/uploads/). Перед этим проверяется расширение файла, его тип, размер и корректность данных. Также функция уникализирует имя файла, чтобы избежать коллизий с уже существующими файлами в каталоге.
Заключение
Функция wp_handle_upload() — это мощный инструмент для обработки загружаемых файлов в WordPress. Она позволяет разработчикам безопасно работать с файлами, загруженными через формы, автоматически проверяя их и перемещая в соответствующий каталог.