wp_update_term( int $term_id, string $taxonomy, array $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

$term_idint

The ID of the term.

$taxonomystring

The taxonomy of the term.

$argsarrayoptional

Array of arguments for updating 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 containing the term_id and term_taxonomy_id, WP_Error otherwise.

Performance profile

How much work a call to wp_update_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 ->get_var().

Scaling

Constant

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

Instructions

16–320

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

Plugin surface

13 hooks

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

Called by

8

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

What it touches

• querycontent queryget_term()called directly
• hookthird-party callbacksapply_filters()called directly
• sqldatabase query->get_var()called directly
• optionoption read or writeget_option()one call below wp_update_term()
• cacheobject cachewp_cache_delete_multiple()one call below wp_update_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 · 65 distinct outcomes

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

Hooks and filters fired · 13

13 hooks fire while wp_update_term() runs, in this order:

1. 1
   apply_filters( wp_update_term_parent )filterline 3321 (+101 into the body)

   Filters the term parent.

2. 2
   do_action( edit_terms )actionline 3356 (+136 into the body)

   Fires immediately before the given terms are edited.

3. 3
   apply_filters( wp_update_term_data )filterline 3370 (+150 into the body)

   Filters term data before it is updated in the database.

4. 4
   do_action( edited_terms )actionline 3390 (+170 into the body)

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

5. 5
   do_action( edit_term_taxonomy )actionline 3402 (+182 into the body)

   Fires immediate before a term-taxonomy relationship is updated.

6. 6
   do_action( edited_term_taxonomy )actionline 3416 (+196 into the body)

   Fires immediately after a term-taxonomy relationship is updated.

7. 7
   do_action( edit_term )actionline 3432 (+212 into the body)

   Fires after a term has been updated, but before the term cache has been cleaned.

8. 8
   do_action( edit_{$taxonomy} )actionline 3452 (+232 into the body)

   Fires after a term in a specific taxonomy has been updated, but before the term cache has been cleaned.

9. 9
   apply_filters( term_id_filter )filterline 3455 (+235 into the body)

   Filters the term ID after a new term is created.

10. 10
    do_action( edited_term )actionline 3473 (+253 into the body)

    Fires after a term has been updated, and the term cache has been cleaned.

11. 11
    do_action( edited_{$taxonomy} )actionline 3493 (+273 into the body)

    Fires after a term for a specific taxonomy has been updated, and the term cache has been cleaned.

12. 12
    do_action( saved_term )actionline 3496 (+276 into the body)

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

13. 13
    do_action( saved_{$taxonomy} )actionline 3499 (+279 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.
• get_term()Gets all term data from database by term ID.
• is_wp_error()Checks whether the given variable is a WordPress Error.
• wp_slash()Adds slashes to a string or recursively adds slashes to strings within an array.
• wp_parse_args()Merges user defined arguments into defaults array.
• sanitize_term()Sanitizes all term fields.
• wp_unslash()Removes slashes from a string or recursively removes slashes from strings within an array.
• term_exists()Determines whether a taxonomy term exists.
• 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.

Used by · 8

• WP_REST_Terms_Controller::update_item()Updates a single term from a taxonomy.
• wp_ajax_inline_save_tax()Handles Quick Edit saving for a term via AJAX.
• wp_check_term_hierarchy_for_loops()Checks the given subset of the term hierarchy for hierarchy loops.
• wp_insert_category()Updates an existing Category or creates a new Category.
• wp_insert_term()Adds a new term to the database.
• wp_update_nav_menu_object()Saves the properties of a menu or create a new menu with those properties.
• wp_update_term()Updates term based on arguments provided.
• wp_xmlrpc_server::wp_editTerm()Edits a term.

Source code

View on Trac ↗View on GitHub ↗

3220function wp_update_term( $term_id, $taxonomy, $args = array() ) {3221	global $wpdb;3222 3223	if ( ! taxonomy_exists( $taxonomy ) ) {3224		return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) );3225	}3226 3227	$term_id = (int) $term_id;3228 3229	// First, get all of the original args.3230	$term = get_term( $term_id, $taxonomy );3231 3232	if ( is_wp_error( $term ) ) {3233		return $term;3234	}3235 3236	if ( ! $term ) {3237		return new WP_Error( 'invalid_term', __( 'Empty Term.' ) );3238	}3239 3240	$term = (array) $term->data;3241 3242	// Escape data pulled from DB.3243	$term = wp_slash( $term );3244 3245	// Merge old and new args with new args overwriting old ones.3246	$args = array_merge( $term, $args );3247 3248	$defaults    = array(3249		'alias_of'    => '',3250		'description' => '',3251		'parent'      => 0,3252		'slug'        => '',3253	);3254	$args        = wp_parse_args( $args, $defaults );3255	$args        = sanitize_term( $args, $taxonomy, 'db' );3256	$parsed_args = $args;3257 3258	// expected_slashed ($name)3259	$name        = wp_unslash( $args['name'] );3260	$description = wp_unslash( $args['description'] );3261 3262	$parsed_args['name']        = $name;3263	$parsed_args['description'] = $description;3264 3265	if ( '' === trim( $name ) ) {3266		return new WP_Error( 'empty_term_name', __( 'A name is required for this term.' ) );3267	}3268 3269	if ( (int) $parsed_args['parent'] > 0 && ! term_exists( (int) $parsed_args['parent'] ) ) {3270		return new WP_Error( 'missing_parent', __( 'Parent term does not exist.' ) );3271	}3272 3273	$empty_slug = false;3274	if ( empty( $args['slug'] ) ) {3275		$empty_slug = true;3276		$slug       = sanitize_title( $name );3277	} else {3278		$slug = $args['slug'];3279	}3280 3281	$parsed_args['slug'] = $slug;3282 3283	$term_group = $parsed_args['term_group'] ?? 0;3284	if ( $args['alias_of'] ) {3285		$alias = get_term_by( 'slug', $args['alias_of'], $taxonomy );3286		if ( ! empty( $alias->term_group ) ) {3287			// The alias we want is already in a group, so let's use that one.3288			$term_group = $alias->term_group;3289		} elseif ( ! empty( $alias->term_id ) ) {3290			/*3291			 * The alias is not in a group, so we create a new one3292			 * and add the alias to it.3293			 */3294			$term_group = $wpdb->get_var( "SELECT MAX(term_group) FROM $wpdb->terms" ) + 1;3295 3296			wp_update_term(3297				$alias->term_id,3298				$taxonomy,3299				array(

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.0.4 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.