MEDIA_HANDLE_SIDELOAD() │ WP 2.6.0

Функция media_handle_sideload() обрабатывает файлы, загружаемые с помощью сторонних источников, так же, как и загруженные файлы через media_handle_upload().

Используемые функции

• wp_handle_sideload() — обрабатывает загрузку файла.
• wp_insert_attachment() — вставляет элемент медиа в базу данных.
• wp_read_image_metadata() — считывает метаданные изображения.
• wp_update_attachment_metadata() — обновляет метаданные элемента медиа.
• wp_generate_attachment_metadata() — генерирует метаданные для загруженного файла.

Возврат значения

Функция возвращает:

• ID элемента медиа в случае успеха.
• WP_Error в случае ошибки.

Применение

Функция используется следующим образом:

media_handle_sideload( $file_array, $post_id, $desc, $post_data );

• $file_array (обязательный) — массив, представляющий собой $_FILES, который содержит загружаемый файл.
• $post_id — ID поста, к которому относится медиафайл. (тип: int)
• $desc — описание загружаемого файла. (тип: string, по умолчанию: null)
• $post_data — данные поста для переопределения. (тип: array, по умолчанию: пустой массив)

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

Пример 1: Загрузка файла по 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';
$post_id = 3061;
$desc = "Логотип WordPress";

// Загружаем файл
$tmp = download_url( $url );

// Проверка на ошибки при загрузке
if ( is_wp_error( $tmp ) ) {
    @unlink( $tmp );
    return $tmp;
}

// Устанавливаем данные файла
$file_array = [
    'name'     => basename( $url ), // например: 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 );

// Файл загружен и должен отобразиться в админ-панели
$value = wp_get_attachment_url( $id ); // Получаем URL загруженного файла

Пример 2: Загрузка файла без привязки к посту

// Подключите необходимые файлы
//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 );

if ( ! is_wp_error( $tmp ) ) {
    // Устанавливаем данные файла
    $file_array = [
        'name'     => basename( $url ),
        'tmp_name' => $tmp
    ];

    $id = media_handle_sideload( $file_array, 0 ); // 0 - без привязки к посту

    // Проверка на ошибки
    if( is_wp_error( $id ) ){
        echo $id->get_error_messages();
    }
}

// Удаляем временный файл
@unlink( $tmp );

Пример 3: Загрузка внешнего изображения и установка миниатюры поста

Функция для загрузки изображения из внешнего источника и установки его в качестве миниатюры поста:

// Инициализация функции
$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; // Флаг отладки, установленный вне функции

    // Подключаем необходимые файлы
    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 'Ошибка, временный файл не создан! 
';
    }

    // Отладочная информация
    if( $debug ){
        echo 'Массив файла: 
';
        var_dump( $file_array );
        echo '
 ID поста: ' . $post_id . '
';
    }

    $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 — Параметр $post_id стал необязательным.

Код функции

function media_handle_sideload( $file_array, $post_id = 0, $desc = null, $post_data = array() ) {
    $overrides = array( 'test_form' => false );

    if ( isset( $post_data['post_date'] ) && substr( $post_data['post_date'], 0, 4 ) > 0 ) {
        $time = $post_data['post_date'];
    } else {
        $post = get_post( $post_id );
        if ( $post && substr( $post->post_date, 0, 4 ) > 0 ) {
            $time = $post->post_date;
        } else {
            $time = current_time( 'mysql' );
        }
    }

    $file = wp_handle_sideload( $file_array, $overrides, $time );

    if ( isset( $file['error'] ) ) {
        return new WP_Error( 'upload_error', $file['error'] );
    }

    $url     = $file['url'];
    $type    = $file['type'];
    $file    = $file['file'];
    $title   = preg_replace( '/.[^.]+$/', '', wp_basename( $file ) );
    $content = '';

    // Используем данные exif/iptc для заголовка и описания
    $image_meta = wp_read_image_metadata( $file );

    if ( $image_meta ) {
        if ( trim( $image_meta['title'] ) && ! is_numeric( sanitize_title( $image_meta['title'] ) ) ) {
            $title = $image_meta['title'];
        }

        if ( trim( $image_meta['caption'] ) ) {
            $content = $image_meta['caption'];
        }
    }

    if ( isset( $desc ) ) {
        $title = $desc;
    }

    // Формируем массив для вложения
    $attachment = array_merge(
        array(
            'post_mime_type' => $type,
            'guid'           => $url,
            'post_parent'    => $post_id,
            'post_title'     => $title,
            'post_content'   => $content,
        ),
        $post_data
    );

    // Это не должно быть установлено, чтобы не перезаписывать существующее вложение.
    unset( $attachment['ID'] );

    // Сохраняем метаданные вложения.
    $attachment_id = wp_insert_attachment( $attachment, $file, $post_id, true );

    if ( ! is_wp_error( $attachment_id ) ) {
        wp_update_attachment_metadata( $attachment_id, wp_generate_attachment_metadata( $attachment_id, $file ) );
    }

    return $attachment_id;
}

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

• download_url() — загружает файл по URL.
• media_handle_upload() — обрабатывает загрузку через форму.
• media_sideload_image() — загружает изображение и добавляет его в библиотеку медиа.