Question

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

Add a new term to the database.

---

description

A non-existent term is inserted in the following sequence:

1. The term is added to the term table, then 相关函数 to the taxonomy.
2. If everything is correct, several actions are fired.
3. The ‘term_id_filter’ is evaluated.
4. The term cache is cleaned.
5. Several more actions are fired.
6. An array is returned containing the term_id and term_taxonomy_id.

If the ‘slug’ argument is not empty, then it is checked to see if the term is invalid. If it is not a valid, existing term, it is added and the term_id is given.

If the taxonomy is hierarchical, and the ‘parent’ argument is not empty, the term is inserted and the term_id will be given.

Error handling: If $taxonomy does not exist or $term is empty, a WP_Error object will be returned.

If the term already exists on the same hierarchical level, or the term slug and name are not unique, a WP_Error object will be returned.

---

参数

$term

(string) (Required) The term to add or update.

$taxonomy

(string) (Required) The taxonomy to which to add the term.

$args

(array|string) (Optional) Array or string of arguments for inserting a term.

• 'alias_of'
  (string) Slug of the term to make this term an alias of. Default empty string. Accepts a term slug.
• 'description'
  (string) The term description. Default empty string.
• 'parent'
  (int) The id of the parent term. Default 0.
• 'slug'
  (string) The term slug to use. Default empty string.

Default value: array()

---

返回值

(array|WP_Error) An array containing the term_id and term_taxonomy_id, WP_Error otherwise.

---

源代码

File: wp-includes/taxonomy.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);
}

---

更新日志

Version	description
2.3.0	Introduced.

---

相关函数

Uses

• wp-includes/taxonomy.php: wp_insert_term_data
• wp-includes/taxonomy.php: edit_terms
• wp-includes/taxonomy.php: edited_terms
• wp-includes/l10n.php: __()
• wp-includes/formatting.php: wp_unslash()
• wp-includes/formatting.php: sanitize_title()
• wp-includes/functions.php: wp_parse_args()
• wp-includes/functions.php: wp_list_pluck()
• wp-includes/taxonomy.php: wp_update_term()
• wp-includes/taxonomy.php: wp_unique_term_slug()
• wp-includes/taxonomy.php: clean_term_cache()
• wp-includes/taxonomy.php: pre_insert_term
• wp-includes/taxonomy.php: create_term
• wp-includes/taxonomy.php: create_{$taxonomy}
• wp-includes/taxonomy.php: term_id_filter
• wp-includes/taxonomy.php: created_term
• wp-includes/taxonomy.php: created_{$taxonomy}
• wp-includes/taxonomy.php: term_exists()
• wp-includes/taxonomy.php: sanitize_term()
• wp-includes/taxonomy.php: get_term_by()
• wp-includes/taxonomy.php: get_terms()
• wp-includes/taxonomy.php: taxonomy_exists()
• wp-includes/taxonomy.php: is_taxonomy_hierarchical()
• wp-includes/plugin.php: apply_filters()
• wp-includes/plugin.php: do_action()
• wp-includes/wp-db.php: wpdb::get_var()
• wp-includes/wp-db.php: wpdb::insert()
• wp-includes/wp-db.php: wpdb::update()
• wp-includes/wp-db.php: wpdb::get_row()
• wp-includes/wp-db.php: wpdb::delete()
• wp-includes/wp-db.php: wpdb::prepare()
• wp-includes/load.php: is_wp_error()
• wp-includes/class-wp-error.php: WP_Error::__construct()
Show 28 more uses Hide more uses

---

Used By

• wp-includes/rest-api/endpoints/class-wp-rest-terms-controller.php: WP_REST_Terms_Controller::create_item()
• wp-admin/includes/class-wp-press-this.php: WP_Press_This::add_category()
• wp-admin/includes/taxonomy.php: wp_insert_category()
• wp-admin/includes/taxonomy.php: wp_create_term()
• wp-admin/includes/ajax-actions.php: _wp_ajax_add_hierarchical_term()
• wp-admin/includes/ajax-actions.php: wp_ajax_add_link_category()
• wp-admin/includes/ajax-actions.php: wp_ajax_add_tag()
• wp-includes/taxonomy.php: wp_set_object_terms()
• wp-includes/nav-menu.php: wp_update_nav_menu_object()
• wp-includes/class-wp-xmlrpc-server.php: wp_xmlrpc_server::wp_newTerm()
• wp-includes/class-wp-xmlrpc-server.php: wp_xmlrpc_server::_insert_post()
Show 6 more used by Hide more used by

---

User Contributed Notes

1. Skip to note content You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note Contributed by erayalakese

   Watch out for invalid taxonomy error for custom taxonomies. This error means you’re calling wp_insert_term before register_taxonomy. Double check your action hooks.

Example

$parent_term = term_exists( 'fruits', 'product' ); // array is returned if taxonomy is given
$parent_term_id = $parent_term['term_id'];         // get numeric term id
wp_insert_term(
	'Apple',   // the term 
	'product', // the taxonomy
	array(
		'description' => 'A yummy apple.',
		'slug'        => 'apple',
		'parent'      => $parent_term_id,
	)
);