Функция wp_insert_attachment() в WordPress используется для добавления вложений (медиафайлов) в базу данных сайта, создавая соответствующую запись в таблице wp_posts. Это полезная функция при разработке, когда нужно автоматизировать процесс загрузки и привязки медиафайлов к постам. Функция не загружает физически файл на сервер, она создает запись о существующем файле в базе данных и возвращает ID нового вложения.
wp_insert_attachment( string|array $args, string|false $file = false, int $parent_post_id, bool $wp_error = false, bool $fire_after_hooks = true ): int|WP_ErrorОписание параметров
- $args (string|array): Обязательный параметр. Массив с данными для записи вложения, включающий такие ключи, как
post_title,post_content,post_status,guid, иpost_mime_type. - $file (string|false): Необязательный параметр. Путь к файлу на сервере. По умолчанию:
false. - $parent_post_id (int): ID родительского поста, к которому прикрепляется вложение. Если значение
0, вложение не будет связано с постом. По умолчанию:0. - $wp_error (bool): Указывает, возвращать ли объект
WP_Errorв случае ошибки. По умолчанию:false. - $fire_after_hooks (bool): Нужно ли запускать хуки после добавления записи. По умолчанию:
true.
Возвращаемое значение
Функция возвращает:
- ID вложения (int), если операция прошла успешно.
- 0 или объект
WP_Error, если произошла ошибка.
Пример 1: Добавление вложения и привязка его к посту
Допустим, у нас есть файл изображения, который был загружен в директорию WordPress, и мы хотим создать запись об этом файле и привязать его к посту с ID 45:
<?php
// Путь к файлу в директории загрузок.
$filename = '/path/to/uploads/2024/10/example-image.jpg';
// ID поста, к которому прикрепляется вложение.
$parent_post_id = 45;
// Определим MIME-тип файла.
$filetype = wp_check_filetype( basename( $filename ), null );
// Получим директорию загрузок.
$wp_upload_dir = wp_upload_dir();
// Подготовим массив данных для вложения.
$attachment = array(
'guid' => $wp_upload_dir['url'] . '/' . basename( $filename ),
'post_mime_type' => $filetype['type'],
'post_title' => preg_replace( '/\.[^.]+$/', '', basename( $filename ) ),
'post_content' => '',
'post_status' => 'inherit'
);
// Добавим вложение в базу данных.
$attach_id = wp_insert_attachment( $attachment, $filename, $parent_post_id );
// Подключаем необходимые файлы.
require_once( ABSPATH . 'wp-admin/includes/image.php' );
// Создаем метаданные для вложения.
$attach_data = wp_generate_attachment_metadata( $attach_id, $filename );
wp_update_attachment_metadata( $attach_id, $attach_data );
?>
В этом примере мы добавляем изображение в медиатеку и привязываем его к посту с ID 45. Также создаются метаданные для файла (например, размеры изображения).
Пример 2: Добавление вложения без привязки к посту
Если нужно загрузить файл в медиатеку без привязки к какому-либо посту, можно передать значение 0 в качестве ID поста:
<?php
// Путь к файлу.
$filename = '/path/to/uploads/2024/10/another-file.pdf';
// Определяем MIME-тип.
$filetype = wp_check_filetype( basename( $filename ), null );
// Получаем директорию загрузок.
$wp_upload_dir = wp_upload_dir();
// Подготовка данных для вложения.
$attachment = array(
'guid' => $wp_upload_dir['url'] . '/' . basename( $filename ),
'post_mime_type' => $filetype['type'],
'post_title' => preg_replace( '/\.[^.]+$/', '', basename( $filename ) ),
'post_content' => '',
'post_status' => 'inherit'
);
// Добавляем запись в базу данных, не привязывая к посту.
$attach_id = wp_insert_attachment( $attachment, $filename, 0 );
// Создаем метаданные для файла.
require_once( ABSPATH . 'wp-admin/includes/image.php' );
$attach_data = wp_generate_attachment_metadata( $attach_id, $filename );
wp_update_attachment_metadata( $attach_id, $attach_data );
?>
Этот пример загружает файл PDF в медиатеку, но не прикрепляет его к какому-либо посту.
Пример 3: Обработка ошибок с использованием WP_Error
Для того чтобы обработать возможные ошибки при добавлении вложения, можно передать параметр $wp_error в значение true:
<?php
// Путь к файлу.
$filename = '/path/to/uploads/2024/10/sample-audio.mp3';
// Получение MIME-типа.
$filetype = wp_check_filetype( basename( $filename ), null );
// Данные вложения.
$attachment = array(
'guid' => $wp_upload_dir['url'] . '/' . basename( $filename ),
'post_mime_type' => $filetype['type'],
'post_title' => preg_replace( '/\.[^.]+$/', '', basename( $filename ) ),
'post_content' => '',
'post_status' => 'inherit'
);
// Вставка вложения с проверкой на ошибки.
$attach_id = wp_insert_attachment( $attachment, $filename, 0, true );
if ( is_wp_error( $attach_id ) ) {
echo 'Ошибка при добавлении вложения: ' . $attach_id->get_error_message();
} else {
echo 'Вложение успешно добавлено с ID: ' . $attach_id;
}
?>
Этот код проверяет, произошла ли ошибка при добавлении вложения, и выводит сообщение об ошибке, если она возникла.
Заключение
Функция wp_insert_attachment() является мощным инструментом для разработчиков WordPress, позволяя автоматически добавлять вложения в медиатеку и привязывать их к постам. Используя её в сочетании с другими функциями, такими как wp_generate_attachment_metadata() и wp_update_attachment_metadata(), можно легко управлять медиафайлами на сайте.