Функция media_sideload_image() – WordPress загрузка изображений

## Функция media_sideload_image()

Функция media_sideload_image() загружает изображение с указанного URL и прикрепляет его к посту в WordPress.

### Использует:

- media_handle_sideload() — функция для обработки загруженных медиафайлов
- download_url() — функция для загрузки файлов по URL

### Хуки функции

- image_sideload_extensions — фильтр для изменения списка допустимых расширений файлов изображений.

### Возвращаемые значения

- **String** | **Int** | **WP_Error**: В случае успеха возвращает HTML-тег <img>, ID вложения или URL вложения. В случае ошибки возвращает объект WP_Error.

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

```php
media_sideload_image( $file, $post_id, $desc, $return_type );

• $file (string) (обязательный): URL изображения, которое нужно загрузить.
• $post_id (int): ID поста, к которому нужно привязать медиафайл.
• $desc (string): Описание изображения.
  • По умолчанию: null
• $return_type (string): Принимает значения 'html' (HTML-тег изображения), 'src' (URL) или 'id' (ID вложения).
  • По умолчанию: 'html'

Пример использования

Загрузка изоб��ажения для поста из внешнего URL

// Подключаем необходимые файлы WordPress
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 = 'http://s.w.org/style/images/wp-header-logo.png'; // URL изображения
$post_id = 3061; // ID поста
$desc = "Логотип WordPress"; // Описание

$img_tag = media_sideload_image( $url, $post_id, $desc );

if( is_wp_error( $img_tag ) ){
    echo $img_tag->get_error_message(); // Показываем сообщение об ошибке
} else {
    // Если файл успешно добавлен, выводим тег изображения
    echo $img_tag;
}

Изменения в версии

• С версии 2.6.0: Функция была введена.
• С версии 4.2.0: Добавлен параметр $return_type.
• С версии 4.8.0: В параметре $return_type появилась опция 'id'.
• С версии 5.3.0: Параметр $post_id стал необязательным.
• С версии 5.4.0: Исходный URL вложения теперь сохраняется в метаданных поста _source_url.
• С версии 5.8.0: Расширение 'webp' добавлено в список допустимых расширений файлов по умолчанию.

Код функции

function media_sideload_image( $file, $post_id = 0, $desc = null, $return_type = 'html' ) {
    if ( ! empty( $file ) ) {

        $allowed_extensions = array( 'jpg', 'jpeg', 'jpe', 'png', 'gif', 'webp' );

        /**
         * Фильтр для изменения списка разрешенных расширений файлов
         * при загрузке изображения по URL.
         */
        $allowed_extensions = apply_filters( 'image_sideload_extensions', $allowed_extensions, $file );
        $allowed_extensions = array_map( 'preg_quote', $allowed_extensions );

        // Получаем имя файла, игнорируя параметры в URL
        preg_match( '/[^?]+.(' . implode( '|', $allowed_extensions ) . ')b/i', $file, $matches );

        if ( ! $matches ) {
            return new WP_Error( 'image_sideload_failed', __( 'Неверный URL изображения.' ) );
        }

        $file_array         = array();
        $file_array['name'] = wp_basename( $matches[0] );

        // Загружаем файл во временное местоположение
        $file_array['tmp_name'] = download_url( $file );

        // Если ошибка при хранении временно, возвращаем ошибку
        if ( is_wp_error( $file_array['tmp_name'] ) ) {
            return $file_array['tmp_name'];
        }

        // Выполняем валидацию и сохраняем файл
        $id = media_handle_sideload( $file_array, $post_id, $desc );

        // Если ошибка при сохранении, удаляем временный файл
        if ( is_wp_error( $id ) ) {
            @unlink( $file_array['tmp_name'] );
            return $id;
        }

        // Сохраняем исходный источник вложения в метаданных
        add_post_meta( $id, '_source_url', $file );

        // Если ID вложения был запрошен, возвращаем его
        if ( 'id' === $return_type ) {
            return $id;
        }

        $src = wp_get_attachment_url( $id );
    }

    // Проверяем, что файл был сохранен, затем возвращаем HTML
    if ( ! empty( $src ) ) {
        if ( 'src' === $return_type ) {
            return $src;
        }

        $alt  = isset( $desc ) ? esc_attr( $desc ) : '';
        $html = "";

        return $html;
    } else {
        return new WP_Error( 'image_sideload_failed' );
    }
}

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

• download_url(): Загружает файл по URL.
• media_handle_sideload(): Обрабатывает медиафайлы после загрузки.
• media_handle_upload(): Обрабатывает медиафайлы, загружаемые через форму.