wp_insert_term()

Добавляет новый термин (рубрику, метку или элемент произвольной таксономии).

Возвращает:

• В случае успеха функция возвращает массив, состоящий из двух ключей – term_id и term_taxonomy_id.
• Объект WP_Error, если:
  • указанной таксономии не существует (или она регистрируется позже),
  • если в первом параметре передано пустое или числовое значение,
  • если термин с указанным ярлыком или именем уже существует,
  • если указан ID несуществующего родительского термина,
  • если по какой-то причине не удалось произвести запись в базу данных.

wp_insert_term( $term, $taxonomy, $args = array() )

Параметры

$term

(строка) Название элемента таксономии, например «Путешествия»

$taxonomy

(строка) Название (ярлык) самой таксономии, к которой будет относиться новый термин, например post_tag.

$args

(массив|строка) Дополнительные аргументы в виде массива или URL-подобной строки:

slug

(строка) Ярлык нового элемента таксономии. Если не указывать, то используется название термина, очищенное функцией sanitize_title().

parent

(целое) ID родительского термина, если это таксономия с иерархией.

description

(строка) Описание термина.

alias_of

(строка) Укажите ярлык уже существующего термина, с которым хотите связать новый. Связываться они будут одинаковыми значениями поля term_group (на практике оно редко где используется, некоторые плагины юзают его для пользовательской сортировки терминов например).

Примеры

В использовании функции нет ничего сложного. Однако, когда создаёте новый термин произвольной таксономии, обратите внимание на порядок выполнения хуков, иначе есть риск словить ошибку WP_Error «Неверная таксономия».

$term = wp_insert_term( 'Новая категория', 'category' );
// ярлык будет взят из названия, он будет "новая-категория"
print_r( $term );
/*
Array
(
    [term_id] => 58
    [term_taxonomy_id] => 58
)
*/

Давайте попробуем немного прокачать наш код и сделать его плюс-минус похожим на реальный:

// исходные данные
$name = 'Новая категория';
$taxonomy = 'category';
 
// сначала нам нужно проверить, что термина не существует
if( ! term_exists( $name, $taxonomy ) ) {
 
	// окей, пробуем добавить рубрику
	$cat = wp_insert_term( $name, $taxonomy );
	if( ! is_wp_error( $cat ) ) {
		echo 'Рубрика добавлена, её ID=' . $cat[ 'term_id' ];
	} else {
		echo $error->get_error_message();
	}
 
}

Хуки

Внутри функции допольно большое количество хуков, которые позволят вам как изменить какие-либо данные термина, так и выполнить какие-либо действия в процессе его добавления.

pre_insert_term

Позволяет изменить название добавляемого термина практически в самом начале функции, перед его очисткой.

С версии 3.0.0

$term = apply_filters( 'pre_insert_term', $term, $taxonomy );

К примеру, вы захотели, чтобы на ваш сайт невозможно было добавить метку «Лыжи», и чтобы она всегда перевоплощалась в «Сноуборд».

add_filter( 'pre_insert_term', 'true_filter_term_name', 25, 2 );
 
function true_filter_term_name( $term, $taxonomy ) {
	// выше я говорил про метки только, поэтому другие таксономии игнорируем
	if( 'post_tag' !== $taxonomy ) {
		return $term;
	}
	if( 'Лыжи' === $term ) {
		$term = 'Сноуборд';
	}
	return $term;
}

Не знаете, как работать с фильтрами?

wp_insert_term_data

Позволяет изменить данные термина непосредственно перед его вставкой в базу данных.

С версии 4.7.0

$data = apply_filters( 'wp_insert_term_data', $data, $taxonomy, $args );

add_filter( 'wp_insert_term_data', 'true_change_term_data', 25, 3 );
 
function true_change_term_data( $data, $taxonomt, $args ) {
 
	// можем изменить один из элементов массива
	// $data[ 'name' ]
	// $data[ 'slug' ]
	// $data[ 'term_group' ]
	return $data;
 
}

create_term

Позволяет совершить какое-либо действие непосредственно после вставки термина в базу данных, но до очистки кэша.

С версии 2.3.0

do_action( 'create_term', $term_id, $tt_id, $taxonomy );

add_action( 'create_term', 'true_do_after_create_term', 25, 3 );
 
function true_do_after_create_term( $term_id, $tt_id, $taxonomy ) {
	// делаем что-либо
}

create_{$taxonomy}

Экшен-хук практически аналогичен хуку create_term, с тем лишь исключением, что название таксономи здесь является частью названия хука, а значит он всегда выполняется только для какой-то одной таксономии.

С версии 2.3.0

do_action( "create_{$taxonomy}", $term_id, $tt_id );

term_id_filter

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

С версии 2.3.0

$term_id = apply_filters( 'term_id_filter', $term_id, $tt_id );

created_term

Срабатывает после добавления термина в базу данных и после очистки кэша.

С версии 2.3.0

do_action( 'created_term', $term_id, $tt_id, $taxonomy );

created_{$taxonomy}

Срабатывает после добавления термина в базу данных и после очистки кэша.

С версии 2.3.0

do_action( "created_{$taxonomy}", $term_id, $tt_id );

saved_term

Срабатывает после добавления термина в базу данных и после очистки кэша.

С версии 5.5.0

do_action( 'saved_term', $term_id, $tt_id, $taxonomy, false );

Четвёртый параметр false в данном случае означает, что мы создаём новый термин. Этот же хук присутствует и в функции wp_update_term(), и там четвёртый параметр уже равен true – то есть обновляем уже существующий элемент таксономии.

saved_{$taxonomy}

Срабатывает после добавления термина в базу данных и после очистки кэша.

С версии 5.5.0

do_action( "saved_{$taxonomy}", $term_id, $tt_id, false );