wp_insert_attachment

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

wp_insert_attachment() нужно использовать в связке с функциями: wp_generate_attachment_metadata() и wp_update_attachment_metadata().

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

Чтобы физически загрузить файл и создать запись этого файла в БД разом, обычно используется функция media_handle_upload().

Хуков нет.

Возвращает

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

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

wp_insert_attachment( $attachment, $filename, $parent_post_id, $wp_error );
$attachment(массив) (обязательный)

Массив данных о добавляемом вложении, который будет записан в БД в таблицу wp_posts. Обязательно должен содержать минимум эти данные: post_title, post_content (в значении указывается пустая строка), post_status, guid и post_mime_type:

$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'
);

$filename(строка)
Расположение файла на сервере. Используйте абсолютный путь, а не УРЛ. Путь должен указывать на директорию загрузок WordPress – uploads. Смотрите wp_upload_dir().
По умолчанию: false
$parent_post_id(число)
ID поста (записи) к которому должен относиться добавляемый медиафайл. Здесь указываем ID поста-родителя.
По умолчанию: 0
$wp_error(логический)
Ставим true, если в случае ошибки нужно вернуть объект WP_Error. C WP 4.7.
По умолчанию: false

Примеры

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

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

<?php
function wp_insert_attachment( $args, $file = false, $parent = 0, $wp_error = false ) {
	$defaults = array(
		'file'        => $file,
		'post_parent' => 0
	);

	$data = wp_parse_args( $args, $defaults );

	if ( ! empty( $parent ) ) {
		$data['post_parent'] = $parent;
	}

	$data['post_type'] = 'attachment';

	return wp_insert_post( $data, $wp_error );
}