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–321

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

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 3311 (+101 into the body)

   Filters the term parent.

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

   Fires immediately before the given terms are edited.

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

   Filters term data before it is updated in the database.

4. 4
   do_action( edited_terms )actionline 3380 (+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 3392 (+182 into the body)

   Fires immediate before a term-taxonomy relationship is updated.

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

   Fires immediately after a term-taxonomy relationship is updated.

7. 7
   do_action( edit_term )actionline 3422 (+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 3442 (+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 3445 (+235 into the body)

   Filters the term ID after a new term is created.

10. 10
    do_action( edited_term )actionline 3463 (+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 3483 (+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 3486 (+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 3489 (+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 ↗

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