media_handle_sideload()
Загружает файл в медиатеку WordPress из переданного массива с данными о файле, аналогично media_handle_upload().
media_handle_upload() работает напрямую с глобальным массивом $_FILES, это не всегда удобно. Иногда удобнее указать произвольные данные файла и обработать их, для этого и нужна эта функция.
Во фронтенде для работы функции нужны следующие файлы:
require_once ABSPATH . 'wp-admin/includes/image.php'; require_once ABSPATH . 'wp-admin/includes/file.php'; require_once ABSPATH . 'wp-admin/includes/media.php';
Если нужно загрузить картинку по URL (именно картинку), используете аналогичную функцию media_sideload_image().
Хуков нет.
Возвращает
int|WP_Error
. ID добавленного вложения. Объект WP_Error в случае неудачи.
Использование
$id = media_handle_sideload( $file_array, $post_id, $desc = null, $post_data = array() );
- $file_array(массив) (обязательный)
- Массив с данными файла - аналогичный $_FILES.
- $post_id(число)
- ID поста, к которому нужно прикрепить файл после загрузки.
С WP 6.3 параметр стал необязательным. - $desc(строка)
- Описание загружаемого файла. Станет значением поля
post_title
вwp_posts
.
По умолчанию: null - $post_data(массив)
Позволяет перезаписывать данные добавляемого вложения. Указываются данные вложения, которые будут записаны в таблицу
wp_posts
:post_parent
,post_title
,post_excerpt
и т.д. По умолчанию:array( 'post_mime_type' => $type, 'guid' => $url, 'post_parent' => $post_id, 'post_title' => $title, 'post_content' => $content, )
По умолчанию: null
Примеры
#1 Загрузка файла по URL
Этот пример показывает как работать с функцией. Этот код загрузит картинку из внешнего источника, добавить её в медиатеку WordPress и прикрепит её к указанному посту:
// во фронтэнде нужны эти файлы //require_once ABSPATH . 'wp-admin/includes/image.php'; //require_once ABSPATH . 'wp-admin/includes/file.php'; //require_once ABSPATH . 'wp-admin/includes/media.php'; $url = 'http://s.w.org/style/images/wp-header-logo.png'; $post_id = 3061; $desc = "Логотип WordPress"; // Загрузим файл $tmp = download_url( $url ); // Установим данные файла $file_array = [ 'name' => basename( $url ), // ex: wp-header-logo.png 'tmp_name' => $tmp, 'error' => 0, 'size' => filesize($tmp), ]; // загружаем файл $id = media_handle_sideload( $file_array, $post_id, $desc ); // если ошибка if( is_wp_error( $id ) ) { @unlink($file_array['tmp_name']); return $id->get_error_messages(); } // удалим временный файл @unlink( $tmp ); // все, файл загружен и должен появится в админке в медиафайлах
#2 Загрузка файла по URL без привязки к конкретному посту
// во фронтэнде нужны эти файлы //require_once ABSPATH . 'wp-admin/includes/image.php'; //require_once ABSPATH . 'wp-admin/includes/file.php'; //require_once ABSPATH . 'wp-admin/includes/media.php'; $url = "http://s.w.org/style/images/wp-header-logo.png"; $desc = "Логотип WordPress"; // загрузим файл $tmp = download_url( $url ); // корректируем умя файла в строках запроса. $file_array = [ 'name' => basename( $url ), 'tmp_name' => $tmp ]; media_handle_sideload( $file_array, 0 ); // удалим временный файл @unlink( $tmp );
#3 Загрузка внешней картинки и установка миниатюры записи
Функция, которая будет загружать внешнюю картинку с указанного УРЛ, сохранять картинку в директорию uploads и прикреплять её к записи как миниатюру:
// инициализация функции $post_id = 3061; $file = 'http://s.w.org/style/images/wp-header-logo.png?1'; if( is_single( $post_id ) ) my_sideload_image( $post_id, $file, $desc = 'Описание картинки' ); // код функции function my_sideload_image( $post_id, $file, $desc = null ){ global $debug; // определяется за пределами функции как true if( ! function_exists('media_handle_sideload') ) { require_once ABSPATH . 'wp-admin/includes/image.php'; require_once ABSPATH . 'wp-admin/includes/file.php'; require_once ABSPATH . 'wp-admin/includes/media.php'; } // Загружаем файл во временную директорию $tmp = download_url( $file ); // Устанавливаем переменные для размещения $file_array = [ 'name' => basename( $file ), 'tmp_name' => $tmp ]; // Удаляем временный файл, при ошибке if ( is_wp_error( $tmp ) ) { $file_array['tmp_name'] = ''; if( $debug ) echo 'Ошибка нет временного файла! <br />'; } // проверки при дебаге if( $debug ){ echo 'File array: <br />'; var_dump( $file_array ); echo '<br /> Post id: ' . $post_id . '<br />'; } $id = media_handle_sideload( $file_array, $post_id, $desc ); // Проверяем работу функции if ( is_wp_error( $id ) ) { var_dump( $id->get_error_messages() ); } else { update_post_meta( $post_id, '_thumbnail_id', $id ); } // удалим временный файл @unlink( $tmp ); }
Список изменений
С версии 2.6.0 | Введена. |
С версии 5.3.0 | The $post_id parameter was made optional. |