WordPress как на ладони
Недорогой хостинг для сайтов на WordPress: wordpress.jino.ru Рекомендуемые продукты со скидкой от Template Monster

wp_insert_term() WP 2.3

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

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

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

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

Используйте wp_update_term(), когда нужно обновить уже существующий термин.

Является основой для: 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

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

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

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

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

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

Примеры

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

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

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

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

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

Заметки

  • Global. wpdb. $wpdb WordPress database abstraction object.

Список изменений

С версии 2.3.0 Введена.

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

<?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'],
			'update_term_meta_cache' => false,
		)
	);

	/*
	 * 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,
						'update_term_meta_cache' => false,
					)
				);

				$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, t.slug, tt.term_taxonomy_id, tt.taxonomy 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 ) );

	/**
	 * Filters the duplicate term check that takes place during term creation.
	 *
	 * Term parent+taxonomy+slug combinations are meant to be unique, and wp_insert_term()
	 * performs a last-minute confirmation of this uniqueness before allowing a new term
	 * to be created. Plugins with different uniqueness requirements may use this filter
	 * to bypass or modify the duplicate-term check.
	 *
	 * @since 5.1.0
	 *
	 * @param object $duplicate_term Duplicate term row from terms table, if found.
	 * @param string $term           Term being inserted.
	 * @param string $taxonomy       Taxonomy name.
	 * @param array  $args           Term arguments passed to the function.
	 * @param int    $tt_id          term_taxonomy_id for the newly created term.
	 */
	$duplicate_term = apply_filters( 'wp_insert_term_duplicate_term_check', $duplicate_term, $term, $taxonomy, $args, $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вязанные функции

Из метки: wp_insert (вставка в БД)

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

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

8 комментов
  • petrozavodsky790 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
    Ответить5.5 лет назад #
    • petrozavodsky790 alkoweb.ru

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

      Ответить5.5 лет назад #
    • Arnold

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

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

    Добрый день.

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

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

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

    Ответить3.2 года назад #
    • Kama7610

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

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

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

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

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

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

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

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

        Ответить3.2 года назад #
  • Николай

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

    Ответить1.9 года назад #
    • Kama7610

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

      Ответить1.9 года назад #
Здравствуйте, !     Войти . Зарегистрироваться