Функция media_sideload_image() в WordPress позволяет загрузить изображение из внешнего URL, сохранить его в медиабиблиотеке и, при необходимости, прикрепить его к посту. Это полезная функция для автоматической загрузки и обработки изображений с удаленных ресурсов, например, при импорте контента.
media_sideload_image( string $file, int $post_id, string $desc = null, string $return_type = 'html' ): string|int|WP_Error
Параметры:
$file(строка, обязательно) — URL изображения, которое необходимо загрузить.$post_id(число, опционально) — ID записи, к которой изображение будет прикреплено. Если не указано, изображение не будет прикреплено к посту.$desc(строка, опционально) — описание изображения, которое на самом деле устанавливает «TITLE» вложения, а не «DESCRIPTION».$return_type(строка, опционально) — Определяет, что возвращает функция:'html'(по умолчанию) — HTML-тег изображения.'src'— URL изображения.'id'— ID вложения.
Возвращаемое значение:
- Строка: HTML-код изображения или URL изображения, в зависимости от значения параметра
$return_type. - Число: ID вложения.
- WP_Error: Объект ошибки, если возникли проблемы при загрузке.
Пример 1: Загрузка изображения с внешнего URL
Для загрузки изображения из удаленного URL на сайт и его прикрепления к записи с ID 1200:
require_once ABSPATH . 'wp-admin/includes/media.php';
require_once ABSPATH . 'wp-admin/includes/file.php';
require_once ABSPATH . 'wp-admin/includes/image.php';
$url = 'https://example.com/images/sample-image.jpg';
$post_id = 1200;
$desc = "Пример изображения";
$image_tag = media_sideload_image($url, $post_id, $desc);
if (is_wp_error($image_tag)) {
echo "Ошибка загрузки: " . $image_tag->get_error_message();
} else {
echo "Изображение успешно загружено: " . $image_tag;
}
В данном примере изображение загружается по указанному URL и прикрепляется к записи с ID 1200. Если загрузка успешна, функция вернет HTML-тег изображения, который можно вставить в код. Если произошла ошибка, выведется сообщение об ошибке.
Пример 2: Возвращение URL изображения вместо HTML-тега
Если вы хотите получить URL загруженного изображения, используйте параметр 'src' в качестве значения $return_type:
$url = 'https://example.com/images/logo.png';
$post_id = 1234;
$image_url = media_sideload_image($url, $post_id, null, 'src');
if (is_wp_error($image_url)) {
echo "Ошибка загрузки: " . $image_url->get_error_message();
} else {
echo "URL изображения: " . $image_url;
}
В этом случае функция вернет URL загруженного изображения, который можно использовать в других местах сайта.
Пример 3: Получение ID вложения
Для получения ID загруженного вложения можно использовать следующий код:
$url = 'https://example.com/images/banner.jpg';
$post_id = 5678;
$image_id = media_sideload_image($url, $post_id, null, 'id');
if (is_wp_error($image_id)) {
echo "Ошибка загрузки: " . $image_id->get_error_message();
} else {
echo "ID вложения: " . $image_id;
}
Этот пример возвращает ID вложения, который можно использовать для дальнейшей работы с медиафайлом, например, для редактирования метаданных или удаления.
Использование функции во фронтэнде
Функция media_sideload_image() изначально предназначена для работы в административной части сайта. Чтобы использовать ее на фронтэнде, необходимо подключить несколько дополнительных файлов:
require_once ABSPATH . 'wp-admin/includes/media.php';
require_once ABSPATH . 'wp-admin/includes/file.php';
require_once ABSPATH . 'wp-admin/includes/image.php';
Без этих файлов функция работать не будет.
Заметки и рекомендации
- Проверка расширений: Функция проверяет расширение файла для безопасности. Если ваше изображение не имеет расширения (что бывает при работе с API), можно обойти проверку, добавив искусственное расширение:
$image_url_with_ext = $url . '#.jpg';
$image_id = media_sideload_image($image_url_with_ext, $post_id, null, 'id');- Обработка ошибок: Обязательно проверяйте возвращаемые значения с помощью функции
is_wp_error(), чтобы корректно обрабатывать возможные ошибки. - Работа с не-графическими файлами: Хотя название функции указывает на работу с изображениями, ее можно использовать для загрузки других типов файлов, если соответствующим образом настроить разрешенные расширения:
add_filter('image_sideload_extensions', function($accepted_extensions) {
$accepted_extensions[] = 'mp3';
return $accepted_extensions;
});Заключение
Функция media_sideload_image() — это мощный инструмент для автоматической загрузки изображений и других файлов с удаленных ресурсов в WordPress. Она предоставляет гибкие возможности для работы с медиафайлами и легко интегрируется в различные сценарии, такие как автоматизированный импорт контента или обработка внешних API.
