Функция wp_insert_term() позволяет добавить новый элемент таксономии (термин) в WordPress. Это полезно для создания новых категорий, меток или пользовательских таксономий. При успешной вставке возвращается массив с идентификаторами термина и таксономии. В случае ошибки функция возвращает объект WP_Error.
wp_insert_term( string $term, string $taxonomy, array|string $args = array() ): array|WP_ErrorФункция вставляет новый термин в несколько шагов:
- Термин добавляется в таблицу
wp_terms. - Привязывается к указанной таксономии в таблице
wp_term_taxonomy. - Если указаны дополнительные параметры, такие как
parent(для древовидных таксономий) илиslug, они обрабатываются. - Функция очищает кэш и вызывает несколько хуков для обновления данных.
Параметры
- $term (string) — Название термина (обязательный параметр).
- $taxonomy (string) — Название таксономии, в которую добавляется термин (обязательный параметр).
- $args (array|string) — Массив или строка параметров для термина (опциональный параметр).
Поддерживаемые параметры в $args:
- description (string) — Описание термина. По умолчанию пустая строка.
- slug (string) — Ярлык термина (название в URL). По умолчанию создается автоматически на основе имени термина.
- parent (int) — Идентификатор родительского термина (если таксономия древовидная).
- alias_of (string) — Ярлык термина, который делает этот термин алиасом другого термина.
Возвращаемое значение
- array — Массив с
term_idиterm_taxonomy_id, если добавление прошло успешно. - WP_Error — Объект с сообщением об ошибке, если что-то пошло не так (например, термин с таким же именем или ярлыком уже существует).
Пример 1: Добавление нового термина с родительским элементом
В этом примере мы добавим новый термин «Яблоко» в таксономию «product» с родительским элементом «fruits».
// Проверяем, существует ли родительский термин "fruits"
$parent_term = term_exists( 'fruits', 'product' ); // вернет массив, если термин существует
$parent_term_id = $parent_term['term_id']; // получаем 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 {
echo 'Новый термин успешно добавлен. ID термина: ' . $insert_res['term_id'];
}
Пример 2: Добавление термина с автоматически созданным slug
В этом примере добавляем новый термин «Оранжевый» в таксономию «color». Если не указать параметр slug, WordPress создаст уникальный slug автоматически на основе названия термина.
$insert_res = wp_insert_term(
'Оранжевый', // название термина
'color' // таксономия
);
// Проверка результата
if ( is_wp_error( $insert_res ) ) {
echo 'Ошибка: ' . $insert_res->get_error_message();
} else {
echo 'Термин "Оранжевый" добавлен с ID: ' . $insert_res['term_id'];
}
Пример 3: Проверка существующего термина и добавление нового
Перед добавлением термина можно проверить, существует ли уже термин с таким же именем.
if ( ! term_exists( 'Яблоко', 'product' ) ) {
$insert_res = wp_insert_term(
'Яблоко', // название термина
'product', // таксономия
array(
'description' => 'Свежий фрукт.',
'slug' => 'apple-fresh'
)
);
if ( is_wp_error( $insert_res ) ) {
echo 'Ошибка: ' . $insert_res->get_error_message();
} else {
echo 'Новый термин "Яблоко" успешно добавлен с ID: ' . $insert_res['term_id'];
}
} else {
echo 'Термин "Яблоко" уже существует в таксономии "product".';
}
Заключение
Функция wp_insert_term() — мощный инструмент для добавления новых терминов в WordPress. Она позволяет гибко управлять параметрами термина и автоматически создает уникальные ярлыки, если они не заданы. При работе с древовидными таксономиями можно задавать родительские элементы, а в случае ошибок функция вернет объект WP_Error с описанием проблемы.