WP_INSERT_POST(): Обновление и вставка записей в WordPress

## Функция WP_INSERT_POST() │ WP 1.0.0

Функция wp_insert_post() позволяет безопасно вставлять или обновлять записи в базе данных WordPress. Она очищает входные данные, выполняет необходимые проверки и заполняет отсутствующие переменные. Например, если не указана дата публикации записи, она будет установлена автоматически.

### Важные моменты

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

- **Указание автора:** Если функция выполняется в контексте, когда пользователь не вошел в систему, например, через CRON или REST API, вы должны указать 'post_author' => user_id. По умолчанию функция назначает ID текущего пользователя, а если пользователь отсутствует, значение будет 0, что может привести к ошибкам.

- **Вызываемые хуки:** Функция вызывает различные хуки, такие как save_post и wp_insert_post. Функции обратного вызова для этих хуков могут зависеть от данных $_POST или $_GET, которые могут быть недоступны на фронтенде. Это может вызывать ошибки, если функция используется на фронтенде — обязательно проверьте наличие проблем в обратных вызовах хуков.

### Информация о записях

Если вам нужна информация о записях в WordPress, обратитесь к документации: **Записи в WordPress**.

---

## Категории

Категории должны передаваться в виде массива чисел, соответствующих ID категорий в базе данных. Это необходимо делать даже если вы указываете только одну категорию.

Для задания терминов записей используйте функцию wp_set_post_terms().

---

## Безопасность (Очистка заголовка записи)

Функция очищает входные данные с помощью sanitize_post(), который проверяет и очищает все поля. Поэтому нет необходимости предварительно оч��щать данные.

Однако вам может понадобиться удалить HTML-теги или нестандартные символы из заголовка записи. WordPress не делает этого автоматически для заголовков. Используйте sanitize_text_field() для этой задачи, особенно если записи могут быть поданы с фронтенда:

```php
// Создание массива данных записи
$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 );

Примечание об эмодзи

С версии 4.2 поддержка эмодзи была добавлена, и функция автоматически преобразует символы эмодзи в полях post_title, post_content и post_excerpt, если кодировка таблицы — utf8, а не utf8mb4. Для этих полей применяется функция wp_encode_emoji().

Возврат значения

Функция возвращает:

• Int | WP_Error.
  • ID записи, если вставка прошла успешно.
  • 0, если параметр $wp_error отключен и произошла ошибка.
  • Объект WP_Error, если параметр $wp_error включен и произошла ошибка.

Шаблон использования

$post_data = [
    'ID'             => ,
    'menu_order'     => ,
    'comment_status' => 'closed' | 'open',
    'ping_status'    => 'closed' | 'open',
    'pinged'         => ?,
    'post_author'    => ,
    'post_content'   => ,
    'post_date'      => 'Y-m-d H:i:s',
    'post_date_gmt'  => 'Y-m-d H:i:s',
    'post_excerpt'   => ,
    'post_name'      => ,
    'post_parent'    => ,
    'post_password'  => ?,
    'post_status'    => 'draft' | 'publish' | 'pending' | 'future' | 'private',
    'post_title'     => ,
    'post_type'      => 'post' | 'page' | 'link' | 'nav_menu_item' | custom post type,
    'post_category'  => array( , <...> ),
    'tags_input'     => array( , , <...> ),
    'tax_input'      => array( 'taxonomy_name' => array( 'term', 'term2', 'term3' ) ),
    'to_ping'        => ?,
    'meta_input'     => [ 'meta_key'=>'meta_value' ],
];

$post_id = wp_insert_post( wp_slash( $post_data ) );

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

1. Простой пример добавления новой записи в базу данных 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).

2. Вставить запись и проверить наличие ошибок

$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()
}

3. Вставка записи с пользовательской таксономией и метаданными

$post_arr = array(
    'post_title'   => 'Тестовая запись',
    'post_content' => 'Контент тестовой записи',
    'post_status'  => 'publish',
    'post_author'  => get_current_user_id(),
    'tax_input'    => array(
        'hierarchical_tax'     => array( 13, 10 ),
        'non_hierarchical_tax' => 'tax name 1, tax name 2',
    ),
    'meta_input'   => array(
        'test_meta_key' => 'значение test_meta_key',
    ),
);

Заметки

• Посмотрите: sanitize_post()
• Глобально: wpdb. Объект абстракции базы данных WordPress.

Изменения

• С версии 1.0.0 — Функция введена.
• С версии 2.6.0 — Добавлен параметр $wp_error для возврата WP_Error в случае ошибки.
• С версии 4.2.0 — Добавлена поддержка кодировки эмодзи в заголовках, контенте и аннотациях записи.
• С версии 5.6.0 — Добавлен параметр $fire_after_hooks.