Функция media_handle_upload() в WordPress: сохранение и создание вложения

# media_handle_upload() │ WP 2.5.0

Функция media_handle_upload() позволяет сохранить файл, отправленный из формы, и создать запись для этого вложения в WordPress.

### Что делает функция

- **Сохраняет** файл на сервере.
- **Создает** новый объект вложения в базе данных.

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

- wp_handle_upload()
- wp_insert_attachment()
- wp_update_attachment_metadata()

### Хуки 

Эта функция не использует хуки.

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

Функция возвращает:
- **ID** вложения (число) или
- объект WP_Error в случае ошибки.

## Как использовать

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

```php
media_handle_upload( $file_id, $post_id, $post_data, $overrides );

Параметры

• $file_id (string, обязательный): Индекс массива $_FILES, из которого был загружен файл.
• $post_id (int, обязательный): ID записи, к которой нужно прикрепить медиафайл. Значение может быть 0, если вы хотите создать медиафайл без привязки к записи.
• $post_data (array): Массив данных для замены некоторых параметров вложения. По умолчанию пустой массив.
• $overrides (array): Замены для поведения функции wp_handle_upload(). По умолчанию пустой массив.

Примеры

1. Загрузка и сохранение файла вложения с помощью пользовательской HTML-формы

Вот пример HTML-формы с полем для загрузки файла. Код должен быть размещен на фронтальной части сайта:

Убедитесь, что в форме указан атрибут enctype="multipart/form-data". Если этого не сделать, $_FILES будет пустым, и media_handle_upload() вернёт ошибку.

Теперь обработаем отправку формы и сохраним файл вложения:

// Проверяем защиту nonce и возможность редактирования записи пользователем.
if (
    isset( $_POST['my_image_upload_nonce'], $_POST['post_id'] )
    && wp_verify_nonce( $_POST['my_image_upload_nonce'], 'my_image_upload' )
    && current_user_can( 'edit_post', $_POST['post_id'] )
) {
    // Все в порядке! Продолжаем.
    require_once ABSPATH . 'wp-admin/includes/image.php';
    require_once ABSPATH . 'wp-admin/includes/file.php';
    require_once ABSPATH . 'wp-admin/includes/media.php';

    // Загрузим файл с помощью встроенной функции WordPress.
    $attachment_id = media_handle_upload( 'my_image_upload', $_POST['post_id'] );

    if ( is_wp_error( $attachment_id ) ) {
        echo 'Ошибка загрузки медиафайла';
    } else {
        echo 'Медиафайл успешно загружен!';
    }
} 
else {
    echo 'Проверка не прошла. Не удалось загрузить файл.';
}

2. Создание загрузки нескольких файлов в WordPress

WordPress позволяет загружать несколько файлов одновременно. Чтобы добавить такую возможность на фронтальной части сайта, создайте шаблон страницы (например, my-upload-page.php) и вставьте следующее:

     Добавьте все файлы здесь:  
    

Эта форма отправляет данные на свою же страницу (action=""), поэтому в коде того же файла (например, my-upload-page.php) необходимо разместить обработчик, как в предыдущем примере.

История изменений

• С версии 2.5.0 — функция была введена.

Исходный код функции media_handle_upload()

function media_handle_upload( $file_id, $post_id, $post_data = array(), $overrides = array( 'test_form' => false ) ) {
    $time = current_time( 'mysql' );
    $post = get_post( $post_id );

    if ( $post ) {
        // Дата публикации записи не имеет значения для страниц, поэтому не устанавливаем дату загрузки.
        if ( 'page' !== $post->post_type && substr( $post->post_date, 0, 4 ) > 0 ) {
            $time = $post->post_date;
        }
    }

    $file = wp_handle_upload( $_FILES[ $file_id ], $overrides, $time );

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

    $name = $_FILES[ $file_id ]['name'];
    $ext  = pathinfo( $name, PATHINFO_EXTENSION );
    $name = wp_basename( $name, ".$ext" );

    $url     = $file['url'];
    $type    = $file['type'];
    $file    = $file['file'];
    $title   = sanitize_text_field( $name );
    $content = '';
    $excerpt = '';

    // Обрабо��ка метаданных для аудио и изображений
    // (код опущен для краткости)

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

    unset( $attachment['ID'] );

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

    if ( ! is_wp_error( $attachment_id ) ) {
        // Устанавливаем заголовок с ID вложения.
        if ( ! headers_sent() ) {
            header( 'X-WP-Upload-Attachment-ID: ' . $attachment_id );
        }

        // Создаем дополнительные размеры изображения.
        wp_update_attachment_metadata( $attachment_id, wp_generate_attachment_metadata( $attachment_id, $file ) );
    }

    return $attachment_id;
}

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

• download_url()
• media_handle_sideload()
• media_sideload_image()
• size_format()
• wp_check_filetype()
• wp_check_filetype_and_ext()
• wp_convert_hr_to_bytes()
• wp_get_upload_dir()
• wp_handle_sideload()
• wp_handle_upload()
• wp_max_upload_size()
• wp_upload_bits()