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

Description

Compatibility

Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.

Parameters

$termstring

The term name to add.

$taxonomystring

The taxonomy to which to add the term.

$argsarray|stringoptional

Array or query string of arguments for inserting a term.Default: array()

• $alias_ofstringdefault: empty string. Accepts a term slug

  Slug of the term to make this term an alias of.

• $descriptionstringdefault: empty string

  The term description.

• $parentintdefault: 0

  The id of the parent term.

• $slugstringdefault: empty string

  The term slug to use.

Return value

array|WP_Error

An array of the new term data, WP_Error otherwise.

• $term_idint

  The new term ID.

• $term_taxonomy_idint|string

  The new term taxonomy ID. Can be a numeric string.

Performance profile

How much work a call to wp_insert_term() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.

Cost class

Heavy

Reaches the database via ->insert().

Scaling

Constant

No loop in the body: the same number of instructions runs whatever you pass in.

Instructions

109–319

Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 492.

Plugin surface

12 hooks

Third-party callbacks on 'pre_insert_term', 'wp_insert_term_data', 'edit_terms' run inside this call, and their cost is not bounded by anything here.

Called by

11

11 places in core call this, so the cost is paid more often than your own code shows.

What it touches

• hookthird-party callbacksapply_filters()called directly
• querycontent queryget_terms()called directly
• sqldatabase query->insert()called directly
• optionoption read or writeget_option()one call below wp_insert_term()
• cacheobject cachewp_cache_delete_multiple()one call below wp_insert_term()

Further down the call graph this can also reach serialize and transient. Those are the worst case, several calls deep and usually down an error path, not what a normal call pays.

What one call costs · 29 distinct outcomes

One number would be a lie: the work depends on which branch runs. These are every distinct cost wp_insert_term() can have, taken from its control-flow graph on PHP 8.5.

This body has more branch combinations than are worth enumerating, so the table covers the outcomes found first rather than every one that exists.

Hooks and filters fired · 12

12 hooks fire while wp_insert_term() runs, in this order:

1. 1
   apply_filters( pre_insert_term )filterline 2475 (+17 into the body)

   Filters a term before it is sanitized and inserted into the database.

2. 2
   apply_filters( wp_insert_term_data )filterline 2622 (+164 into the body)

   Filters term data before it is inserted into the database.

3. 3
   do_action( edit_terms )actionline 2635 (+177 into the body)

   Fires immediately before the given terms are edited.

4. 4
   do_action( edited_terms )actionline 2639 (+181 into the body)

   Fires immediately after a term is updated in the database, but before its term-taxonomy relationship is updated.

5. 5
   apply_filters( wp_insert_term_duplicate_term_check )filterline 2682 (+224 into the body)

   Filters the duplicate term check that takes place during term creation.

6. 6
   do_action( create_term )actionline 2712 (+254 into the body)

   Fires immediately after a new term is created, before the term cache is cleaned.

7. 7
   do_action( create_{$taxonomy} )actionline 2732 (+274 into the body)

   Fires after a new term is created for a specific taxonomy.

8. 8
   apply_filters( term_id_filter )filterline 2744 (+286 into the body)

   Filters the term ID after a new term is created.

9. 9
   do_action( created_term )actionline 2762 (+304 into the body)

   Fires after a new term is created, and after the term cache has been cleaned.

10. 10
    do_action( created_{$taxonomy} )actionline 2782 (+324 into the body)

    Fires after a new term in a specific taxonomy is created, and after the term cache has been cleaned.

11. 11
    do_action( saved_term )actionline 2799 (+341 into the body)

    Fires after a term has been saved, and the term cache has been cleared.

12. 12
    do_action( saved_{$taxonomy} )actionline 2820 (+362 into the body)

    Fires after a term in a specific taxonomy has been saved, and the term cache has been cleared.

Uses · 18

• taxonomy_exists()Determines whether the taxonomy name exists.
• __()Retrieves the translation of $text.
• apply_filters()Calls the callback functions that have been added to a filter hook.
• is_wp_error()Checks whether the given variable is a WordPress Error.
• wp_parse_args()Merges user defined arguments into defaults array.
• term_exists()Determines whether a taxonomy term exists.
• sanitize_term()Sanitizes all term fields.
• wp_unslash()Removes slashes from a string or recursively removes slashes from strings within an array.
• sanitize_title()Sanitizes a string into a slug, which can be used in URLs or HTML attributes.
• get_term_by()Gets all term data from database by term field and data.
• wp_update_term()Updates term based on arguments provided.
• get_terms()Retrieves the terms in a given taxonomy or list of taxonomies.

Used by · 11

• WP_REST_Terms_Controller::create_item()Creates a single term in a taxonomy.
• _wp_ajax_add_hierarchical_term()Handles adding a hierarchical term via AJAX.
• register_taxonomy()Creates or modifies a taxonomy object.
• wp_ajax_add_link_category()Handles adding a link category via AJAX.
• wp_ajax_add_tag()Handles adding a tag via AJAX.
• wp_create_term()Adds a new term to the database if it does not already exist.
• wp_insert_category()Updates an existing Category or creates a new Category.
• wp_set_object_terms()Creates term and taxonomy relationships.
• wp_update_nav_menu_object()Saves the properties of a menu or create a new menu with those properties.
• wp_xmlrpc_server::_insert_post()Helper method for wp_newPost() and wp_editPost(), containing shared logic.
• wp_xmlrpc_server::wp_newTerm()Creates a new term.

Source code

View on Trac ↗View on GitHub ↗

2458function wp_insert_term( $term, $taxonomy, $args = array() ) {2459	global $wpdb;2460 2461	if ( ! taxonomy_exists( $taxonomy ) ) {2462		return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) );2463	}2464 2465	/**2466	 * Filters a term before it is sanitized and inserted into the database.2467	 *2468	 * @since 3.0.02469	 * @since 6.1.0 The `$args` parameter was added.2470	 *2471	 * @param string|WP_Error $term     The term name to add, or a WP_Error object if there's an error.2472	 * @param string          $taxonomy Taxonomy slug.2473	 * @param array|string    $args     Array or query string of arguments passed to wp_insert_term().2474	 */2475	$term = apply_filters( 'pre_insert_term', $term, $taxonomy, $args );2476 2477	if ( is_wp_error( $term ) ) {2478		return $term;2479	}2480 2481	if ( is_int( $term ) && 0 === $term ) {2482		return new WP_Error( 'invalid_term_id', __( 'Invalid term ID.' ) );2483	}2484 2485	if ( '' === trim( $term ) ) {2486		return new WP_Error( 'empty_term_name', __( 'A name is required for this term.' ) );2487	}2488 2489	$defaults = array(2490		'alias_of'    => '',2491		'description' => '',2492		'parent'      => 0,2493		'slug'        => '',2494	);2495	$args     = wp_parse_args( $args, $defaults );2496 2497	if ( (int) $args['parent'] > 0 && ! term_exists( (int) $args['parent'] ) ) {2498		return new WP_Error( 'missing_parent', __( 'Parent term does not exist.' ) );2499	}2500 2501	$args['name']     = $term;2502	$args['taxonomy'] = $taxonomy;2503 2504	// Coerce null description to strings, to avoid database errors.2505	$args['description'] = (string) $args['description'];2506 2507	$args = sanitize_term( $args, $taxonomy, 'db' );2508 2509	// expected_slashed ($name)2510	$name        = wp_unslash( $args['name'] );2511	$description = wp_unslash( $args['description'] );2512	$parent      = (int) $args['parent'];2513 2514	// Sanitization could clean the name to an empty string that must be checked again.2515	if ( '' === $name ) {2516		return new WP_Error( 'invalid_term_name', __( 'Invalid term name.' ) );2517	}2518 2519	$slug_provided = ! empty( $args['slug'] );2520	if ( ! $slug_provided ) {2521		$slug = sanitize_title( $name );2522	} else {2523		$slug = $args['slug'];2524	}2525 2526	$term_group = 0;2527	if ( $args['alias_of'] ) {2528		$alias = get_term_by( 'slug', $args['alias_of'], $taxonomy );2529		if ( ! empty( $alias->term_group ) ) {2530			// The alias we want is already in a group, so let's use that one.2531			$term_group = $alias->term_group;2532		} elseif ( ! empty( $alias->term_id ) ) {2533			/*2534			 * The alias is not in a group, so we create a new one2535			 * and add the alias to it.2536			 */2537			$term_group = $wpdb->get_var( "SELECT MAX(term_group) FROM $wpdb->terms" ) + 1;

Changelog

Introduced in 2.3.0. Unchanged from 6.7.7 through 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data

Generated from the wordpress-develop 7.1.0 tag, from src/wp-includes/taxonomy.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.

Corrections

Something wrong on this page? Report it and it gets fixed in the next regeneration.