WP_INSERT_TERM() – добавление нового элемента в базу данных WordPress

# WP_INSERT_TERM() │ WP 2.3.0

Функция WP_INSERT_TERM() добавляет новый элемент таксономии (термин, категория) в базу данных WordPress. 

С помощью этой функции можно связать новый термин с существующим, сделав его дочерним.

## Как работает WP_INSERT_TERM()

Когда вы добавляете несуществующий термин, процесс проходит в следующем порядке:

1. Сначала термин вставляется в таблицу терминов.
2. Затем он связывается с указанной таксономией.
3. Если всё прошло успешно, срабатывают несколько действий перед фильтром term_id_filter.
4. Оценивается фильтр term_id_filter.
5. Очищается кэш терминов.
6. Срабатывают ещё несколько действий после term_id_filter.
7. Возвращается массив, содержащий term_id и term_taxonomy_id.

Для обновления существующего термина используется функция wp_update_term().

### Пример использования: wp_insert_category()

## Хуки функции

Функция WP_INSERT_TERM() использует несколько хуков:

- pre_insert_term
- wp_insert_term_data
- edit_terms
- edited_terms
- wp_insert_term_duplicate_term_check
- create_term
- create_(taxonomy)
- create_category
- create_post_tag
- term_id_filter
- created_term
- created_(taxonomy)
- created_category
- created_post_tag
- saved_term
- saved_(taxonomy)
- saved_category
- saved_post_tag

## Возвращаемое значение

Функция может вернуть массив или объект WP_Error.

Если всё прошло успешно, в массив будут возвращены значения двух полей таблицы:

```php
array(
    'term_id' => 12,
    'term_taxonomy_id' => 34
)

Если произошла ошибка, будет возвращен объект WP_Error, например:

• Если $taxonomy не существует или $term пуст.
• Если термин уже существует на том же уровне иерархии или с таким же слагом и именем.

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

wp_insert_term( $term, $taxonomy, array(
    'description' => '',
    'parent'      => 0,
    'slug'        => '',
) );

Параметры функции

• $term (строка, обязательный) — Имя термина, который нужно добавить или обновить.
• $taxonomy (строка, обязательный) — Имя таксономии, к которой нужно добавить термин.
• $args (массив/строка) — Массив или строка аргументов для вставки термина. Параметры:
  • $description (строка) — Описание термина. По умолчанию: ''.
  • $parent (целое число) — ID родительского термина. По умолчанию: 0. Указывать родителя можно только если текущая таксономия иерархическая, и указанный родитель существует.
  • $slug (строка) — Слаг термина (используется в URL). По умолчанию: sanitize_title( $term ). Если указать слаг, будет проверено, доступен ли он (если термин с таким слагом уже существует, то он не будет добавлен).
  • $alias_of (строка) — Слаг термина, который будет являться псевдонимом для текущего термина. Если у псевдонима нет группы, она будет создана. На практике поле term_group не используется.

Пример добавления нового термина "ЯБЛОКО" в таксономию "Товар"

Перед вставкой можно автоматически проверить и получить ID родительского термина "фрукты":

$parent_term = term_exists('фрукты', 'product'); // возвращает массив, если таксономия существует
$parent_term_id = $parent_term['term_id'];       // получаем числовое значение термина

$insert_res = wp_insert_term(
    'Яблоко',   // новый термин
    'product',  // таксономия
    array(
        'description' => 'Укус яблока.',
        'slug'        => 'apple',
        'parent'      => $parent_term_id
    )
);

if (is_wp_error($insert_res)) {
    echo $insert_res->get_error_message();
} else {
    $term_id = $insert_res['term_id'];
}

Примечания

• Глобальная переменная wpdb — это объект абстракции базы данных WordPress.

Изменения

Функция была представлена в версии 2.3.0.

Связанные функции

Функции для вставки:

• wp_insert_attachment()
• wp_insert_category()
• wp_insert_comment()
• wp_insert_post()
• wp_insert_user()

Функции для работы с терминами:

• category_exists()
• get_term()
• get_term_by()
• get_terms()
• term_exists()
• и многие другие.

Функции для работы с таксономиями:

• register_taxonomy()
• is_taxonomy_hierarchical()
• taxonomy_exists()
• и другие.