wp_insert_attachment() │ WP 2.0.0

Добавляет медиафайл (вложение) в медиатеку WordPress. Файл физически не добавляется — функция создает запись в таблице wp_posts в базе данных и возвращает ID созданной записи.

Эта функция - одна из функций API низкого уровня, которая используется в WordPress для вставки вложений.

Хуков нет.

Возвращает

int|WP_Error. ID записи в случае успешного добавления и 0 при неудаче. WP_Error объект при неудаче, если указан параметр $wp_error (с версии 4.7).

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

wp_insert_attachment( $args, $file, $parent_post_id, $wp_error, $fire_after_hooks );

$args(массив) (обязательный)

Массив данных о добавляемом вложении, который будет записан в БД в таблицу wp_posts.

При добавлении, должен содержать эти данные:

$args = [
	'guid'           => $url_to_attachment,
	'post_mime_type' => $headers['content-type'],
	'post_title'     => $file_basename,
	// не обязательные
	'post_excerpt'   => $caption,
	'post_content'   => $description,
];

Где,

• guid — УРЛ на файл. Это поле желательно указать, потому это оно будет использоваться в фукнциях которые возвращют УРЛ на файл.
• post_mime_type — миме тип вложения например image/jpg.
• post_title — название файла, которое будет отображаться в админке. Обычно последняя часть УРЛ.
• post_content — обычно используется как описание картинки в атрибуте alt.
• post_excerpt — обычно используется как подпись к картинке.

Ожидает экранированные данные. Это значит, если в функцию передаются не POST данные, то перед отправкой нужно обработать массив данных функцией wp_slash()

$file(строка)

Расположение файла на сервере. Используйте абсолютный путь, а не УРЛ. Путь должен указывать на директорию загрузок WordPress - uploads. Смотрите wp_upload_dir().

После добавления данных в wp_posts, этот параметр передается в фукнцию update_attached_file().

По умолчанию: false

$parent_post_id(число)

ID поста (записи) к которому должен относиться добавляемый медиафайл. Здесь указываем ID поста-родителя.
По умолчанию: 0

$wp_error(логический)

Ставим true, если в случае ошибки нужно вернуть объект WP_Error.
По умолчанию: false

$fire_after_hooks(логический) (WP 5.6)

Нужно ли запускать функцию wp_after_insert_post(), которая запускает хуки в конце работы функции.
По умолчанию: true

Примеры

#1 Добавим записи о файле в базу данных WP

Предполагается, что физически файл уже загружен в директорию uploads и теперь нам нужно добавить запись об этом файле в базу данных WordPress. Также, прикрепим запись к посту 37:

// файл должен находиться в директории загрузок WP.
$filename = '/path/to/uploads/2013/03/filname.jpg';

// ID поста, к которому прикрепим вложение.
$parent_post_id = 37;

// Проверим тип поста, который мы будем использовать в поле 'post_mime_type'.
$filetype = wp_check_filetype( basename( $filename ), null );

// Получим путь до директории загрузок.
$wp_upload_dir = wp_upload_dir();

// Подготовим массив с необходимыми данными для вложения.
$args = [
	'guid'           => $wp_upload_dir['url'] . '/' . basename( $filename ),
	'post_mime_type' => $filetype['type'],
	'post_title'     => preg_replace( '/\.[^.]+$/', '', basename( $filename ) ),
	'post_content'   => '',
];

// Вставляем запись в базу данных.
$attach_id = wp_insert_attachment( $args, $filename, $parent_post_id );

// Подключим нужный файл, если он еще не подключен
// wp_generate_attachment_metadata() зависит от этого файла.
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 );