WordPress как на ладони
Мощный и не дорогой хостинг от Fornex.com

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'];

Код wp_insert_term: wp-includes/taxonomy.php VER 5.0.1

<?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вязанные функции

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

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

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

8 комментов
  • petrozavodsky773 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
    Ответить4.7 года назад #
    • petrozavodsky773 cайт: alkoweb.ru

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

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

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

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

    Добрый день.

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

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

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

    Ответить2.4 года назад #
    • Kama7144

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

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

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

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

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

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

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

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

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

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

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

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

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