Безопасно вставляет/обновляет запись в базе данных.
Функция очищает передаваемые данные; делает некоторые проверки; заполняет пропущенные переменные (например, если не передать дату поста, то дата будет получена автоматически).
Ожидает экранированные данные. Это значит, если в функцию передаются не POST данные, то перед отправкой нужно обработать массив данных функцией wp_slash()
ВАЖНО! Указать 'post_author' => user_id, если код вызывается не из под юзера, например, через CRON, REST и т.д. По умолчанию туда вставляется ИД текущего пользователя, и если текущего юзера нет, то получим 0 и кучу багов.
Имейте ввиду, в функции срабатывают разные хуки, например save_post, wp_insert_post. В колбэках этих хуков могут быть использованы $_POST/$_GET данные, но они могут отсутствовать во фронте. Поэтому могут быть ошибки, когда функция используется во фронте - ищите ошибки в функциях хуков.
Что конкретно понимается под записями, читайте в этой статье: Записи в WordPress
Категории
Категории нужно передавать в виде массива чисел, совпадающих с ID категорий в базе данных. Это относится и к случаю, когда передается одна категория.
Функция обрабатывает переданные данные с помощью функции sanitize_post() - она проверяет и очищает значения всех полей. Поэтому можно не беспокоится об очистке передаваемых данных.
Однако, возможно вам нужно будет удалить HTML теги и другие нестандартные символы из заголовка записи. WordPress не делает это автоматически для заголовка. Это можно сделать использовав sanitize_text_field(), особенно это актуально, когда посты можно публиковать с фронт-энда:
// Создаем массив данных новой записи
$post_data = array(
'post_title' => sanitize_text_field( $_POST['post_title'] ),
'post_content' => $_POST['post_content'],
'post_status' => 'publish',
'post_author' => 1,
'post_category' => array( 8,39 )
);
// Вставляем запись в базу данных
$post_id = wp_insert_post( $post_data );
emoji заметка
C версии 4.2, с введением смайликов эмодзи. Функция автоматически конвертирует символы-смайликов в полях 'post_title', 'post_content', 'post_excerpt', если кодировка таблицы utf8, а не utf8mb4. К этим полям применяется функция wp_encode_emoji().
Массив данных, которые нужно вставить в Базу Данных. Ключи массива в точности равны полям таблицы wp_posts, передаваемые значения ключей будут вставлены в значение полей таблицы.
Если указать ID, то мы обновляем запись, а не создаем новую.
ID(int)
ID записи, которую нужно обновить. Если равно 0 или не указанно то будет добавлена новая запись. По умолчанию: 0.
post_author(int)
ID пользователя, который добавил запись. По умолчанию: ID текущего пользователя.
post_date(string)
Дата публикации записи в формате Y-m-d H:i:s.
Дата поста определяется из post_date, post_date_gmt, если ничего не указано, то будет взято текущее время. См: wp_resolve_post_date() По умолчанию: текущее время.
post_date_gmt(string)
Дата публикации в часовом поясе GMT в формате Y-m-d H:i:s. По умолчанию: дата на основе значения $post_date.
post_content(string)
Полный текст записи. По умолчанию: ''
post_content_filtered(string)
Отфильтрованное содержимое записи. По умолчанию: ''
post_title(string)
Заголовок (название) записи. По умолчанию: ''
post_excerpt(string)
Краткий отрывок записи. По умолчанию: ''
Если статус указывается как future, то обязательно нужно указать дату post_date, чтобы WordPress знал когда опубликовать запись.
По умолчанию: 'draft'.
post_type(string)
Тип записи. Пр: 'post' | 'page' | 'link' | 'nav_menu_item' | custom post type По умолчанию: 'post'.
comment_status(string)
Разрешение на комментарии. Одно из: 'open' или 'closed'. По умолчанию: значение опции 'default_comment_status'
ping_status(string)
Возможность принимать пингбэки. Одно из: 'open' или 'closed'. По умолчанию: значение опции 'default_ping_status'
post_password(string)
Пароль для доступа к записи (для просмотра записи). По умолчанию: ''
post_name(string)
Альтернативное название записи (slug) будет использовано в УРЛе.
Если не указать, то будет взять заголовок записи пропущенный через функцию sanitize_title(). По умолчанию: очищенный заголовок записи.
to_ping(string)
Список URL для пинга, разделённый пробелами или символами перевода строки. По умолчанию: пусто.
pinged(string)
Список URL, которые были пингованы, разделённый пробелами или символами перевода строки. По умолчанию: пусто.
post_parent(int)
ID родительской записи, если применимо. По умолчанию: 0
menu_order(int)
Порядок отображения записи. Если запись "постоянная страница", установите её порядок в меню. По умолчанию: 0
post_mime_type(string)
MIME-тип записи. По умолчанию: ''
guid(string)
Глобальный уникальный идентификатор для ссылки на запись. По умолчанию: пусто.
import_id(int)
ID записи, который будет использован при вставке новой записи. Если указан, он не должен совпадать с ID уже существующей записи. По умолчанию: 0.
post_category(int[])
Категория к которой относится пост (указываем ярлыки, имена или ID).
Формат: [ cat, cat2, ... ]. По умолчанию: используется значение опции 'default_category'.
tags_input(array)
Метки поста (указываем ярлыки, имена или ID).
Формат: [ tag, tag2, ... ]. По умолчанию: пусто.
tax_input(array)
К каким таксономиям прикрепить запись (указываем ярлыки, имена или ID).
Формат: [ 'tax_name' => [ 'term', 'term2' ] ].
Есть некоторые нюансы, в зависимости от того древовидная таксономия или нет. Если таксономия иерархическая, список терминов должен быть массивом ID или строкой ID, разделённой запятыми. Если таксономия не иерархическая, список терминов может быть массивом с именами или слагами, либо строкой с именами или слагами, разделёнными запятыми. Подробнее читайте тут wp_set_post_terms().
Заметка: если пользователь не имеет прав работать с таксономиями то параметр tax_input работать не будет. В этом случае прикрепить термины можно через функцию wp_set_object_terms().
По умолчанию: пусто.
meta_input(array)
Массив мета-полей записи в формате: [ 'meta_key' => 'meta_value' ]. По умолчанию: пусто
page_template(string)
Шаблон страницы, который нужно использовать.
Заметка: поле таблицы page_template было удалено, теперь, шаблон для постоянной страницы задается в метаполе _wp_page_template — там храниться название php файла шаблона.
$wp_error(логический)
Установите в true, чтобы функция вернула WP_Error объект при ошибке. По умолчанию: false
$fire_after_hooks(логический) (WP 5.6)
Нужно ли запускать функцию wp_after_insert_post(), которая запускает хуки в конце работы функции. По умолчанию: true
Примеры
В массиве данных, который передается функции, как минимум нужно указать заголовок и текст записи (ключи массива: post_title и post_content) иначе запись не будет создана. Значения для остальных важных но не указанных полей будут автоматически сгенерированы, например поля post_date, post_author.
1
#1 Вставка поста с таксономией и метаданными поста
$post_id = wp_insert_post( $POST['post_data'], true );
if( is_wp_error( $post_id ) ){
echo $post_id->get_error_message();
}
else {
// теперь можно использовать $post_id, чтобы например добавить
// произвольные поля записи с помощью add_post_meta() или update_post_meta()
}
0
#3 Простой пример вставки новой записи в Базу Данных WordPress:
// Создаем массив
$post_data = array(
'post_title' => 'Заголовок записи',
'post_content' => 'Здесь должен быть контент (текст) записи.',
'post_status' => 'publish',
'post_author' => 1,
'post_category' => array(8,39)
);
// Вставляем данные в БД
$post_id = wp_insert_post( wp_slash($post_data) );
Категории нужно передавать в массиве, даже если указывается одна категория. Например: 'post_category' => array(8)
Смотрите также: wp_set_post_terms(), когда нужно установить произвольные таксономии для поста или типа записи.