wp_insert_term()

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

Возвращает:

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

Параметры

$term

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

$taxonomy

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

$args

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

slug

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

parent

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

description

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

alias_of

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

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 );