WordPress как на ладони
wordpress jino

wp_insert_term() WP 2.3

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

Можно задать связь нового элемента с уже существующим (сделать его дочерним, см. параметры).

Несуществующий термин вставляется в следующей последовательности:

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

Массив/WP_error.

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

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

WP_error вернется при ошибках:

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

  • Также проверяется, не существует ли уже термин с таким же именем или ярлыком на том же уровне «древовидности» таксономии.

Использование

wp_insert_term( $term, $taxonomy, array(
	'description' => '',
	'parent'      => 0,
	'slug'        => '',
) );
$term(строка/число) (обязательный)
Термин, который нужно добавить или обновить.
$taxonomy(строка) (обязательный)
Таксономия к которой будет добавлен термин.
$args(строка/массив)

Изменить значения уже вставленного термина.
По умолчанию: нет

  • description (строка)
    Описание термина (рубрики).
    По умолчанию: ''

  • parent (число)
    Родительский термин для вновь вставляемого.
    По умолчанию: 0

  • slug (строка)
    Ярлык нового термина (название в URL).
    По умолчанию: sanitize_title( $term )

  • alias_of (строка)
    Ярлык (слаг) термина, чтобы сделать этот термин алиасом.

    Тут указывается ярлык термина, у которого нужно взять группу - поле term_group и использовать это число для текущего добавляемого термина. Если у указанного в alias_of термина нет группы, то она будет создана (будет создано число). На практике term_group нигде не используется. С помощью него предполагалось объединять термины, чтобы показывать записи из группы...
    По умолчанию: ''

Если указан аргумент 'slug', то он будет проверен на доступность (не существует ли уже термина с таким же слагом). Если такого термина еще нет, то термин будет добавлен.

Если указан аргумент 'parent', термин будет добавлен только если таксономия древовидная и указанный в parent термин существует.

Примеры

#1. Пример вставки нового термина "Яблоко" в таксономию "product".

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

$parent_term = term_exists( 'fruits', 'product' ); // вернет массив, если таксономия существует
$parent_term_id = $parent_term['term_id']; // получим числовое значения термина
$data = wp_insert_term(
	'Яблоко', // новый термин
	'product', // таксономия
	array(
		'description' => 'Надкусанное яблоко.',
		'slug'        => 'apple',
		'parent'      => $parent_term_id
	)
);

if( ! is_wp_error($data) ) $term_id = $data['term_id'];

Код wp insert term: wp-includes/taxonomy.php WP 4.9

<?php
function wp_insert_term( $term, $taxonomy, $args = array() ) {
	global $wpdb;

	if ( ! taxonomy_exists($taxonomy) ) {
		return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) );
	}
	/**
	 * Filters a term before it is sanitized and inserted into the database.
	 *
	 * @since 3.0.0
	 *
	 * @param string $term     The term to add or update.
	 * @param string $taxonomy Taxonomy slug.
	 */
	$term = apply_filters( 'pre_insert_term', $term, $taxonomy );
	if ( is_wp_error( $term ) ) {
		return $term;
	}
	if ( is_int( $term ) && 0 == $term ) {
		return new WP_Error( 'invalid_term_id', __( 'Invalid term ID.' ) );
	}
	if ( '' == trim( $term ) ) {
		return new WP_Error( 'empty_term_name', __( 'A name is required for this term.' ) );
	}
	$defaults = array( 'alias_of' => '', 'description' => '', 'parent' => 0, 'slug' => '');
	$args = wp_parse_args( $args, $defaults );

	if ( $args['parent'] > 0 && ! term_exists( (int) $args['parent'] ) ) {
		return new WP_Error( 'missing_parent', __( 'Parent term does not exist.' ) );
	}

	$args['name'] = $term;
	$args['taxonomy'] = $taxonomy;

	// Coerce null description to strings, to avoid database errors.
	$args['description'] = (string) $args['description'];

	$args = sanitize_term($args, $taxonomy, 'db');

	// expected_slashed ($name)
	$name = wp_unslash( $args['name'] );
	$description = wp_unslash( $args['description'] );
	$parent = (int) $args['parent'];

	$slug_provided = ! empty( $args['slug'] );
	if ( ! $slug_provided ) {
		$slug = sanitize_title( $name );
	} else {
		$slug = $args['slug'];
	}

	$term_group = 0;
	if ( $args['alias_of'] ) {
		$alias = get_term_by( 'slug', $args['alias_of'], $taxonomy );
		if ( ! empty( $alias->term_group ) ) {
			// The alias we want is already in a group, so let's use that one.
			$term_group = $alias->term_group;
		} elseif ( ! empty( $alias->term_id ) ) {
			/*
			 * The alias is not in a group, so we create a new one
			 * and add the alias to it.
			 */
			$term_group = $wpdb->get_var("SELECT MAX(term_group) FROM $wpdb->terms") + 1;

			wp_update_term( $alias->term_id, $taxonomy, array(
				'term_group' => $term_group,
			) );
		}
	}

	/*
	 * Prevent the creation of terms with duplicate names at the same level of a taxonomy hierarchy,
	 * unless a unique slug has been explicitly provided.
	 */
	$name_matches = get_terms( $taxonomy, array(
		'name' => $name,
		'hide_empty' => false,
		'parent' => $args['parent'],
	) );

	/*
	 * The `name` match in `get_terms()` doesn't differentiate accented characters,
	 * so we do a stricter comparison here.
	 */
	$name_match = null;
	if ( $name_matches ) {
		foreach ( $name_matches as $_match ) {
			if ( strtolower( $name ) === strtolower( $_match->name ) ) {
				$name_match = $_match;
				break;
			}
		}
	}

	if ( $name_match ) {
		$slug_match = get_term_by( 'slug', $slug, $taxonomy );
		if ( ! $slug_provided || $name_match->slug === $slug || $slug_match ) {
			if ( is_taxonomy_hierarchical( $taxonomy ) ) {
				$siblings = get_terms( $taxonomy, array( 'get' => 'all', 'parent' => $parent ) );

				$existing_term = null;
				if ( ( ! $slug_provided || $name_match->slug === $slug ) && in_array( $name, wp_list_pluck( $siblings, 'name' ) ) ) {
					$existing_term = $name_match;
				} elseif ( $slug_match && in_array( $slug, wp_list_pluck( $siblings, 'slug' ) ) ) {
					$existing_term = $slug_match;
				}

				if ( $existing_term ) {
					return new WP_Error( 'term_exists', __( 'A term with the name provided already exists with this parent.' ), $existing_term->term_id );
				}
			} else {
				return new WP_Error( 'term_exists', __( 'A term with the name provided already exists in this taxonomy.' ), $name_match->term_id );
			}
		}
	}

	$slug = wp_unique_term_slug( $slug, (object) $args );

	$data = compact( 'name', 'slug', 'term_group' );

	/**
	 * Filters term data before it is inserted into the database.
	 *
	 * @since 4.7.0
	 *
	 * @param array  $data     Term data to be inserted.
	 * @param string $taxonomy Taxonomy slug.
	 * @param array  $args     Arguments passed to wp_insert_term().
	 */
	$data = apply_filters( 'wp_insert_term_data', $data, $taxonomy, $args );

	if ( false === $wpdb->insert( $wpdb->terms, $data ) ) {
		return new WP_Error( 'db_insert_error', __( 'Could not insert term into the database.' ), $wpdb->last_error );
	}

	$term_id = (int) $wpdb->insert_id;

	// Seems unreachable, However, Is used in the case that a term name is provided, which sanitizes to an empty string.
	if ( empty($slug) ) {
		$slug = sanitize_title($slug, $term_id);

		/** This action is documented in wp-includes/taxonomy.php */
		do_action( 'edit_terms', $term_id, $taxonomy );
		$wpdb->update( $wpdb->terms, compact( 'slug' ), compact( 'term_id' ) );

		/** This action is documented in wp-includes/taxonomy.php */
		do_action( 'edited_terms', $term_id, $taxonomy );
	}

	$tt_id = $wpdb->get_var( $wpdb->prepare( "SELECT tt.term_taxonomy_id FROM $wpdb->term_taxonomy AS tt INNER JOIN $wpdb->terms AS t ON tt.term_id = t.term_id WHERE tt.taxonomy = %s AND t.term_id = %d", $taxonomy, $term_id ) );

	if ( !empty($tt_id) ) {
		return array('term_id' => $term_id, 'term_taxonomy_id' => $tt_id);
	}
	$wpdb->insert( $wpdb->term_taxonomy, compact( 'term_id', 'taxonomy', 'description', 'parent') + array( 'count' => 0 ) );
	$tt_id = (int) $wpdb->insert_id;

	/*
	 * Sanity check: if we just created a term with the same parent + taxonomy + slug but a higher term_id than
	 * an existing term, then we have unwittingly created a duplicate term. Delete the dupe, and use the term_id
	 * and term_taxonomy_id of the older term instead. Then return out of the function so that the "create" hooks
	 * are not fired.
	 */
	$duplicate_term = $wpdb->get_row( $wpdb->prepare( "SELECT t.term_id, tt.term_taxonomy_id FROM $wpdb->terms t INNER JOIN $wpdb->term_taxonomy tt ON ( tt.term_id = t.term_id ) WHERE t.slug = %s AND tt.parent = %d AND tt.taxonomy = %s AND t.term_id < %d AND tt.term_taxonomy_id != %d", $slug, $parent, $taxonomy, $term_id, $tt_id ) );
	if ( $duplicate_term ) {
		$wpdb->delete( $wpdb->terms, array( 'term_id' => $term_id ) );
		$wpdb->delete( $wpdb->term_taxonomy, array( 'term_taxonomy_id' => $tt_id ) );

		$term_id = (int) $duplicate_term->term_id;
		$tt_id   = (int) $duplicate_term->term_taxonomy_id;

		clean_term_cache( $term_id, $taxonomy );
		return array( 'term_id' => $term_id, 'term_taxonomy_id' => $tt_id );
	}

	/**
	 * Fires immediately after a new term is created, before the term cache is cleaned.
	 *
	 * @since 2.3.0
	 *
	 * @param int    $term_id  Term ID.
	 * @param int    $tt_id    Term taxonomy ID.
	 * @param string $taxonomy Taxonomy slug.
	 */
	do_action( "create_term", $term_id, $tt_id, $taxonomy );

	/**
	 * Fires after a new term is created for a specific taxonomy.
	 *
	 * The dynamic portion of the hook name, `$taxonomy`, refers
	 * to the slug of the taxonomy the term was created for.
	 *
	 * @since 2.3.0
	 *
	 * @param int $term_id Term ID.
	 * @param int $tt_id   Term taxonomy ID.
	 */
	do_action( "create_{$taxonomy}", $term_id, $tt_id );

	/**
	 * Filters the term ID after a new term is created.
	 *
	 * @since 2.3.0
	 *
	 * @param int $term_id Term ID.
	 * @param int $tt_id   Taxonomy term ID.
	 */
	$term_id = apply_filters( 'term_id_filter', $term_id, $tt_id );

	clean_term_cache($term_id, $taxonomy);

	/**
	 * Fires after a new term is created, and after the term cache has been cleaned.
	 *
	 * @since 2.3.0
	 *
	 * @param int    $term_id  Term ID.
	 * @param int    $tt_id    Term taxonomy ID.
	 * @param string $taxonomy Taxonomy slug.
	 */
	do_action( 'created_term', $term_id, $tt_id, $taxonomy );

	/**
	 * Fires after a new term in a specific taxonomy is created, and after the term
	 * cache has been cleaned.
	 *
	 * The dynamic portion of the hook name, `$taxonomy`, refers to the taxonomy slug.
	 *
	 * @since 2.3.0
	 *
	 * @param int $term_id Term ID.
	 * @param int $tt_id   Term taxonomy ID.
	 */
	do_action( "created_{$taxonomy}", $term_id, $tt_id );

	return array('term_id' => $term_id, 'term_taxonomy_id' => $tt_id);
}

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

Из метки: term (термины таксономий)

Еще из раздела: Любые таксономии

wp_insert_term 13 комментариев
Вопросы 1 Все
  • petrozavodsky706 cайт: alkoweb.ru

    Одно очень важное замечание, сейчас пишу sax парсер CommerceML 2 но не суть сам дурак, так вот в процессе возникла потребность создавать каиегории постов с древовидной иерархией пробую создавать как то так

    wp_insert_term($term,'category');
    
    $cat_parent = term_exists( $term );
    
    wp_insert_term($term,'category', array('parent'=>$cat_parent));

    получаю две не дочерние друг другу категории или одну только (там разные варианты пробовал не хочу уже воспроизводить оба варианта) факт то что не получается создать иерархию, пом сброс опции

    delete_option("category_children");

    если после создания родительской категории сбросить эту опцию древовидная структура прекрасно создается, соответственно если нужно сбросить другую древовидную таксономию то

    delete_option("другой_тип_таксономии_children");

    ,
    надеюсь это сэкономит кому-то время.

    2
    Ответить3.7 года назад #
    • petrozavodsky706 cайт: alkoweb.ru

      и да по возможности не пишите sax парсеры неблагодарное это дело laugh

      Ответить3.7 года назад #
    • Arnold

      Спасибо! Очень помогло "delete_option("другой_тип_таксономии_children");"

      Ответитьмесяц назад #
  • Ильдар

    Добрый день.

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

    При попытке использовать wp_insert_term получаю "Invalid taxonomy", что логично, т.к. wp_insert_term проверяет существование таксономии через taxonomy_exists, которая не знает кастомных таксономий.

    Как быть? Писать свой вариант добавления термина или как-то можно зарегистрировать в глобальную $wp_taxonomies?

    Ответить1.3 года назад #
    • Kama4662

      Ничего не понятно...

      Создал кастомный тип записей, для парсинга новостей, для него создал таксономию

      Таксономию кастомную значит создал тоже

      что логично, т.к. wp_insert_term проверяет существование таксономии через taxonomy_exists, которая не знает кастомных таксономий.

      Как же не знает, когда до этого ты создал таксономию? taxonomy_exists() прекрасно знает о кастомных таксах! Конечно только в случае, если taxonomy_exists() вызывается после того, как отработал код, который добавляет кастомную таксу и она была добавлена в глобальную переменную.

      Что-то ты не то делаешь. wp_insert_term() должна работать!

      Ответить1.3 года назад #
      • Ильдар

        Да, был неправ, вызывал файл напрямую, видимо из-за этого моя таксономия не успевала инициализироваться. Если функцию вешать на init или на wp-крон, то все работает как нужно.

        Ответить1.3 года назад #
  • Друзья, а правильно ли я понимаю, что элементу массива, который может принимать нулевое значение вполне допустимо присвоить вывод функции которая в случае чего может вернуть false? т.е. 0 и false равнозначны?
    Ну например вот так:

    $args = array(
    'alias_of'=>'Novokuzneck',
    'description'=>'Город-герой Новокузнецк',
    'parent'=> term_exists('goroda'),
    'slug'=>'novokuzneck'
    );
    wp_insert_term('Novokuzneck' 'geo', $args );
  • Николай cайт: vk.com/nikolays_93

    аргумент alias_of (обязательный) но в примере его нету, поправьте.

    • Kama4662

      Неправильное было описание - это необязательный аргумент, поправил. Спасибо за наводку thank_you

  • Николай

    На какой хук вешать выполнение wp_insert_term()?

    Ответитьмесяц назад #
    • Kama4662

      Он на хук не вешается, а вызывается обычно в фукнции, или в файле. Обычно это после события init.

      Ответитьмесяц назад #
  • В чем суть аргумента alias_of? Что он делает, за что отвечает фактически?

    1
    Ответить16 дней назад #
    • Kama4662

      Не используемое поле это... Дополнил описание:

      Тут указывается ярлык термина, у которого нужно взять группу - поле term_group и использовать это число для текущего добавляемого термина. Если у указанного в alias_of термина нет группы, то она будет создана (будет создано число). На практике term_group нигде не используется. С помощью него предполагалось объединять термины, чтобы показывать записи из группы...

      Ответить16 дней назад #

Здравствуйте, !

Ваш комментарий