media_handle_upload()

Сохраняет файл, отправленный из запроса POST, и создает запись вложения для него
Функция WordPress
INT 2.5.0
WordPress Icon
Содержание
  1. Описание функции
  2. Примеры использования
  3. Сохранение и создание вложения
  4. Загрузка и привязка медиа-файла к посту
  5. Перезапись данных вложения
  6. Изменение поведения функции wp_handle_upload()
  7. Обработка ошибок при загрузке
  8. Определение уникального имени файла
  9. Ограничение типов файлов
  10. Вопросы и ответы
  11. Как сохранить файл, отправленный через POST-запрос, и создать вложение для него?
  12. Как привязать медиа-файл к определенному посту?
  13. Можно ли создать медиа-файл без привязки к посту?
  14. Как перезаписать некоторые данные вложения?
  15. Как изменить поведение функции wp_handle_upload()?
  16. Как обработать ошибку при загрузке файла?
  17. Как определить уникальное имя файла при загрузке?
  18. Как проверить размер файла при загрузке?
  19. Как проверить тип файла при загрузке?
  20. Связанные элементы

Описание функции

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

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

media_handle_upload( string $file_id, int $post_id, array $post_data = array(), array $overrides = array('test_form' => false) ): int|WP_Error

Функция media_handle_upload() принимает следующие параметры:

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

Функция media_handle_upload() возвращает идентификатор вложения или объект WP_Error в случае ошибки.

<?php
// Проверяем, был ли отправлен файл
if (isset($_FILES['my_file'])) {
    $file_id = 'my_file'; // Индекс массива $_FILES, в котором был отправлен файл
    $post_id = 0; // Идентификатор записи, к которой будет прикреплен медиа-файл. Установлен в 0, чтобы создать медиа-файл без связи с записью
    $post_data = array(); // Перезаписываемые данные вложения
    $overrides = array('test_form' => false); // Переопределение поведения функции wp_handle_upload()
    // Вызываем функцию media_handle_upload()
    $attachment_id = media_handle_upload($file_id, $post_id, $post_data, $overrides);
    // Проверяем результат
    if (is_wp_error($attachment_id)) {
        // Обработка ошибки
        $error_message = $attachment_id->get_error_message();
        echo "Ошибка загрузки файла: $error_message";
    } else {
        // Файл успешно загружен
        echo "Файл успешно загружен. Идентификатор вложения: $attachment_id";
    }
}
?>

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

Сохранение и создание вложения


$file_id = 'file'; // Index of the $_FILES array that the file was sent
$post_id = 123; // The post ID of a post to attach the media item to
$attachment_id = media_handle_upload($file_id, $post_id);
if (is_wp_error($attachment_id)) {
    // Handle error
} else {
    // Attachment saved successfully
    echo 'Attachment ID: ' . $attachment_id;
}

Загрузка и привязка медиа-файла к посту


$file_id = 'file'; // Index of the $_FILES array that the file was sent
$post_id = 123; // The post ID of a post to attach the media item to
$attachment_id = media_handle_upload($file_id, $post_id);
if (is_wp_error($attachment_id)) {
    // Handle error
} else {
    // Attachment saved successfully
    echo 'Attachment ID: ' . $attachment_id;
}

Перезапись данных вложения


$file_id = 'file'; // Index of the $_FILES array that the file was sent
$post_id = 123; // The post ID of a post to attach the media item to
$post_data = array(
    'post_title' => 'New Title',
    'post_content' => 'New Content'
);
$attachment_id = media_handle_upload($file_id, $post_id, $post_data);
if (is_wp_error($attachment_id)) {
    // Handle error
} else {
    // Attachment saved successfully with updated data
    echo 'Attachment ID: ' . $attachment_id;
}

Изменение поведения функции wp_handle_upload()


$file_id = 'file'; // Index of the $_FILES array that the file was sent
$post_id = 123; // The post ID of a post to attach the media item to
$overrides = array(
    'test_form' => true,
    'upload_error_handler' => 'custom_error_handler',
    'unique_filename_callback' => 'custom_unique_filename_callback',
    'upload_error_strings' => array(
        1 => 'The uploaded file exceeds the upload_max_filesize directive in php.ini.',
        2 => 'The uploaded file exceeds the MAX_FILE_SIZE directive that was specified in the HTML form.',
        3 => 'The uploaded file was only partially uploaded.',
        4 => 'No file was uploaded.',
        6 => 'Missing a temporary folder.',
        7 => 'Failed to write file to disk.',
        8 => 'A PHP extension stopped the file upload.',
    ),
    'test_size' => true,
    'test_type' => true,
    'mimes' => array(
        'jpg|jpeg|jpe' => 'image/jpeg',
        'gif' => 'image/gif',
        'png' => 'image/png',
    )
);
$attachment_id = media_handle_upload($file_id, $post_id, array(), $overrides);
if (is_wp_error($attachment_id)) {
    // Handle error
} else {
    // Attachment saved successfully with custom behavior
    echo 'Attachment ID: ' . $attachment_id;
}
function custom_error_handler($file, $message) {
    // Custom error handling logic
}
function custom_unique_filename_callback($dir, $name, $ext) {
    // Custom logic to generate a unique filename
    return $name . '-' . uniqid() . $ext;
}

Обработка ошибок при загрузке


$file_id = 'file'; // Index of the $_FILES array that the file was sent
$post_id = 123; // The post ID of a post to attach the media item to
$attachment_id = media_handle_upload($file_id, $post_id);
if (is_wp_error($attachment_id)) {
    $errors = $attachment_id->get_error_messages();
    
    foreach ($errors as $error) {
        echo 'Error: ' . $error;
    }
} else {
    // Attachment saved successfully
    echo 'Attachment ID: ' . $attachment_id;
}

Определение уникального имени файла


$file_id = 'file'; // Index of the $_FILES array that the file was sent
$post_id = 123; // The post ID of a post to attach the media item to
$attachment_id = media_handle_upload($file_id, $post_id);
if (is_wp_error($attachment_id)) {
    // Handle error
} else {
    // Attachment saved successfully with unique filename
    echo 'Attachment ID: ' . $attachment_id;
}
function custom_unique_filename_callback($dir, $name, $ext) {
    // Custom logic to generate a unique filename
    return $name . '-' . uniqid() . $ext;
}

Ограничение типов файлов


$file_id = 'file'; // Index of the $_FILES array that the file was sent
$post_id = 123; // The post ID of a post to attach the media item to
$overrides = array(
    'mimes' => array(
        'jpg|jpeg|jpe' => 'image/jpeg',
        'gif' => 'image/gif',
        'png' => 'image/png',
    )
);
$attachment_id = media_handle_upload($file_id, $post_id, array(), $overrides);
if (is_wp_error($attachment_id)) {
    // Handle error
} else {
    // Attachment saved successfully with restricted file types
    echo 'Attachment ID: ' . $attachment_id;
}

Вопросы и ответы

Как сохранить файл, отправленный через POST-запрос, и создать вложение для него?

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

Для использования функции необходимо передать следующие параметры:

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

Функция возвращает идентификатор вложения или объект WP_Error в случае ошибки.

Пример использования функции:


$file_id = 'file'; // индекс массива $_FILES, в котором находится файл
$post_id = 123; // идентификатор поста, к которому будет привязано вложение
// Сохранение файла и создание вложения
$attachment_id = media_handle_upload($file_id, $post_id);
if (is_wp_error($attachment_id)) {
  // Обработка ошибки
  $error_message = $attachment_id->get_error_message();
  echo "Ошибка при загрузке файла: " . $error_message;
} else {
  // Вложение успешно создано
  echo "Файл успешно загружен. ID вложения: " . $attachment_id;
}

Как привязать медиа-файл к определенному посту?

Для привязки медиа-файла к определенному посту необходимо передать идентификатор поста в параметр $post_id функции media_handle_upload().

Пример использования функции:


$file_id = 'file'; // индекс массива $_FILES, в котором находится файл
$post_id = 123; // идентификатор поста, к которому будет привязано вложение
// Сохранение файла и создание вложения
$attachment_id = media_handle_upload($file_id, $post_id);

Можно ли создать медиа-файл без привязки к посту?

Да, можно создать медиа-файл без привязки к посту. Для этого необходимо передать 0 в параметр $post_id функции media_handle_upload().

Пример использования функции:


$file_id = 'file'; // индекс массива $_FILES, в котором находится файл
$post_id = 0; // создание вложения без привязки к посту
// Сохранение файла и создание вложения
$attachment_id = media_handle_upload($file_id, $post_id);

Как перезаписать некоторые данные вложения?

Для перезаписи некоторых данных вложения при использовании функции media_handle_upload() можно передать массив $post_data в качестве третьего параметра. В этом массиве можно указать значения для следующих ключей:

  • post_title: Заголовок вложения.
  • post_content: Содержимое вложения.
  • post_excerpt: Краткое описание вложения.
  • post_status: Статус вложения (например, «publish», «draft», «private»).
  • post_mime_type: MIME-тип файла.

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


$file_id = 'file'; // Индекс в массиве $_FILES, по которому файл был отправлен
$post_id = 123; // ID записи, к которой будет прикреплено вложение
$post_data = array(
  'post_title' => 'Новое название вложения',
  'post_content' => 'Новое содержимое вложения',
  'post_status' => 'publish',
  'post_mime_type' => 'image/jpeg'
);
$attachment_id = media_handle_upload($file_id, $post_id, $post_data);

Как изменить поведение функции wp_handle_upload()?

Для изменения поведения функции wp_handle_upload(), которая используется внутри функции media_handle_upload(), можно передать массив $overrides в качестве четвертого параметра. В этом массиве можно указать значения для следующих ключей:

  • upload_error_handler: Функция, которая будет вызвана при возникновении ошибки в процессе загрузки файла.
  • unique_filename_callback: Функция, которая будет вызвана для определения уникального имени файла.
  • upload_error_strings: Массив строк, описывающих ошибку, указанную в $_FILES[{form field}][‘error’].
  • test_form: Флаг, указывающий, нужно ли проверять параметр $_POST[‘action’].
  • test_size: Флаг, указывающий, нужно ли проверять размер файла (должен быть больше нуля байт).
  • test_type: Флаг, указывающий, нужно ли проверять MIME-тип файла.
  • mimes: Массив разрешенных MIME-типов файлов, указанных по расширению файла.

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


$file_id = 'file'; // Индекс в массиве $_FILES, по которому файл был отправлен
$post_id = 123; // ID записи, к которой будет прикреплено вложение
$overrides = array(
  'upload_error_handler' => 'my_custom_error_handler',
  'unique_filename_callback' => 'my_custom_unique_filename',
  'upload_error_strings' => array(
    UPLOAD_ERR_INI_SIZE => 'Размер файла превышает допустимый предел.',
    UPLOAD_ERR_FORM_SIZE => 'Размер файла превышает допустимый предел, указанный в форме.',
    UPLOAD_ERR_PARTIAL => 'Файл был загружен только частично.',
    UPLOAD_ERR_NO_FILE => 'Файл не был загружен.',
    UPLOAD_ERR_NO_TMP_DIR => 'Отсутствует временная папка для загрузки.',
    UPLOAD_ERR_CANT_WRITE => 'Не удалось записать файл на диск.',
    UPLOAD_ERR_EXTENSION => 'Загрузка файла была остановлена расширением PHP.'
  ),
  'test_form' => true,
  'test_size' => true,
  'test_type' => true,
  'mimes' => array(
    'jpg|jpeg|jpe' => 'image/jpeg',
    'gif' => 'image/gif',
    'png' => 'image/png'
  )
);
$attachment_id = media_handle_upload($file_id, $post_id, array(), $overrides);

Как обработать ошибку при загрузке файла?

При возникновении ошибки в процессе загрузки файла, функция media_handle_upload() может вернуть объект WP_Error. Чтобы обработать эту ошибку, можно воспользоваться функцией wp_handle_upload_error(). Пример использования:


$file_id = 'file'; // Индекс в массиве $_FILES, по которому файл был отправлен
$post_id = 123; // ID записи, к которой будет прикреплено вложение
$attachment_id = media_handle_upload($file_id, $post_id);
if (is_wp_error($attachment_id)) {
  $error_message = wp_handle_upload_error($attachment_id);
  echo 'Ошибка загрузки файла: ' . $error_message;
}

Как определить уникальное имя файла при загрузке?

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

Для определения уникального имени файла используется функция wp_unique_filename(). Она принимает два аргумента: путь к директории, в которой будет сохранен файл, и имя файла. Функция проверяет, существует ли файл с таким именем в указанной директории. Если файл существует, к имени файла добавляется уникальный суффикс.

Пример кода:


$upload_dir = wp_upload_dir(); // Получаем директорию для загрузки файлов
$file_name = $_FILES['file']['name']; // Получаем имя загружаемого файла
$unique_file_name = wp_unique_filename( $upload_dir['path'], $file_name ); // Определяем уникальное имя файла
// Загружаем файл с уникальным именем
$attachment_id = media_handle_upload( 'file', 0, array(), array( 'unique_filename_callback' => 'wp_unique_filename' ) );

Как проверить размер файла при загрузке?

При загрузке файла можно проверить его размер, чтобы убедиться, что он соответствует заданным требованиям.

Функция media_handle_upload() позволяет проверить размер файла с помощью параметра test_size. Если параметр установлен в true, функция проверит, что размер файла больше нуля байт.

Пример кода:


// Загружаем файл и проверяем его размер
$attachment_id = media_handle_upload( 'file', 0, array(), array( 'test_size' => true ) );

Как проверить тип файла при загрузке?

При загрузке файла можно проверить его тип, чтобы убедиться, что он соответствует заданным требованиям.

Функция media_handle_upload() позволяет проверить тип файла с помощью параметра test_type. Если параметр установлен в true, функция проверит, что MIME-тип файла соответствует ожидаемому типу.

Пример кода:


// Загружаем файл и проверяем его тип
$attachment_id = media_handle_upload( 'file', 0, array(), array( 'test_type' => true ) );

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

Связанные элементы

  • Функция wp_handle_upload(): Обрабатывает загружаемый файл и перемещает его в указанную папку.
  • Функция wp_unique_filename(): Генерирует уникальное имя файла для загружаемого файла.
  • Хук wp_handle_upload_prefilter: Позволяет изменить параметры загружаемого файла перед его обработкой.
  • Хук wp_handle_upload: Вызывается после обработки загружаемого файла.
  • Хук wp_ajax_{$action}: Вызывается при выполнении асинхронного запроса AJAX.
  • Класс WP_Error: Представляет ошибку, которая может возникнуть при выполнении операции.
  • Класс WP_Post: Представляет запись в блоге WordPress.
  • Класс WP_Query: Используется для выполнения запросов к базе данных WordPress и получения соответствующих записей.
  • Класс WP_Http: Используется для выполнения HTTP-запросов в WordPress.
Мультимедиа
Обсуждение

Этот сайт использует cookie для хранения данных. Продолжая использовать сайт, Вы принимаете условия пользовательского соглашения и даете свое согласие на использование cookie.