Question

wp_update_term( int $term_id,  string $taxonomy,  array|string $args = array() )

Update term based on arguments provided.

---

description

The $args will indiscriminately override all values with the same field name. Care must be taken to not override important information need to update or update will fail (or perhaps create a new term, neither would be acceptable).

Defaults will set ‘alias_of’, ‘description’, ‘parent’, and ‘slug’ if not defined in $args already.

‘alias_of’ will create a term group, if it doesn’t already exist, and update it for the $term.

If the ‘slug’ argument in $args is missing, then the ‘name’ in $args will be used. It should also be noted that if you set ‘slug’ and it isn’t unique then a WP_Error will be passed back. If you don’t pass any slug, then a unique one will be created for you.

For what can be overrode in $args, check the term scheme can contain and stay away from the term keys.

---

参数

$term_id

(int) (Required) The ID of the term

$taxonomy

(string) (Required) The context in which to relate the term to the object.

$args

(array|string) (Optional) Array of get_terms() arguments.

Default value: array()

---

返回值

(array|WP_Error) Returns Term ID and Taxonomy Term ID

---

源代码

File: wp-includes/taxonomy.php

function wp_update_term( $term_id, $taxonomy, $args = array() ) {
	global $wpdb;

	if ( ! taxonomy_exists( $taxonomy ) ) {
		return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) );
	}

	$term_id = (int) $term_id;

	// First, get all of the original args
	$term = get_term( $term_id, $taxonomy );

	if ( is_wp_error( $term ) ) {
		return $term;
	}

	if ( ! $term ) {
		return new WP_Error( 'invalid_term', __( 'Empty Term' ) );
	}

	$term = (array) $term->data;

	// Escape data pulled from DB.
	$term = wp_slash( $term );

	// Merge old and new args with new args overwriting old ones.
	$args = array_merge($term, $args);

	$defaults = array( 'alias_of' => '', 'description' => '', 'parent' => 0, 'slug' => '');
	$args = wp_parse_args($args, $defaults);
	$args = sanitize_term($args, $taxonomy, 'db');
	$parsed_args = $args;

	// expected_slashed ($name)
	$name = wp_unslash( $args['name'] );
	$description = wp_unslash( $args['description'] );

	$parsed_args['name'] = $name;
	$parsed_args['description'] = $description;

	if ( '' == trim( $name ) ) {
		return new WP_Error( 'empty_term_name', __( 'A name is required for this term.' ) );
	}

	if ( $parsed_args['parent'] > 0 && ! term_exists( (int) $parsed_args['parent'] ) ) {
		return new WP_Error( 'missing_parent', __( 'Parent term does not exist.' ) );
	}

	$empty_slug = false;
	if ( empty( $args['slug'] ) ) {
		$empty_slug = true;
		$slug = sanitize_title($name);
	} else {
		$slug = $args['slug'];
	}

	$parsed_args['slug'] = $slug;

	$term_group = isset( $parsed_args['term_group'] ) ? $parsed_args['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,
			) );
		}

		$parsed_args['term_group'] = $term_group;
	}

	/**
	 * Filters the term parent.
	 *
	 * Hook to this filter to see if it will cause a hierarchy loop.
	 *
	 * @since 3.1.0
	 *
	 * @param int    $parent      ID of the parent term.
	 * @param int    $term_id     Term ID.
	 * @param string $taxonomy    Taxonomy slug.
	 * @param array  $parsed_args An array of potentially altered update arguments for the given term.
	 * @param array  $args        An array of update arguments for the given term.
	 */
	$parent = apply_filters( 'wp_update_term_parent', $args['parent'], $term_id, $taxonomy, $parsed_args, $args );

	// Check for duplicate slug
	$duplicate = get_term_by( 'slug', $slug, $taxonomy );
	if ( $duplicate && $duplicate->term_id != $term_id ) {
		// If an empty slug was passed or the parent changed, reset the slug to something unique.
		// Otherwise, bail.
		if ( $empty_slug || ( $parent != $term['parent']) ) {
			$slug = wp_unique_term_slug($slug, (object) $args);
		} else {
			/* translators: 1: Taxonomy term slug */
			return new WP_Error('duplicate_term_slug', sprintf(__('The slug “%s” is already in use by another term'), $slug));
		}
	}

	$tt_id = (int) $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) );

	// Check whether this is a shared term that needs splitting.
	$_term_id = _split_shared_term( $term_id, $tt_id );
	if ( ! is_wp_error( $_term_id ) ) {
		$term_id = $_term_id;
	}

	/**
	 * Fires immediately before the given terms are edited.
	 *
	 * @since 2.9.0
	 *
	 * @param int    $term_id  Term ID.
	 * @param string $taxonomy Taxonomy slug.
	 */
	do_action( 'edit_terms', $term_id, $taxonomy );

	$data = compact( 'name', 'slug', 'term_group' );

	/**
	 * Filters term data before it is updated in the database.
	 *
	 * @since 4.7.0
	 *
	 * @param array  $data     Term data to be updated.
	 * @param int    $term_id  Term ID.
	 * @param string $taxonomy Taxonomy slug.
	 * @param array  $args     Arguments passed to wp_update_term().
	 */
	$data = apply_filters( 'wp_update_term_data', $data, $term_id, $taxonomy, $args );

	$wpdb->update( $wpdb->terms, $data, compact( 'term_id' ) );
	if ( empty($slug) ) {
		$slug = sanitize_title($name, $term_id);
		$wpdb->update( $wpdb->terms, compact( 'slug' ), compact( 'term_id' ) );
	}

	/**
	 * Fires immediately after the given terms are edited.
	 *
	 * @since 2.9.0
	 *
	 * @param int    $term_id  Term ID
	 * @param string $taxonomy Taxonomy slug.
	 */
	do_action( 'edited_terms', $term_id, $taxonomy );

	/**
	 * Fires immediate before a term-taxonomy relationship is updated.
	 *
	 * @since 2.9.0
	 *
	 * @param int    $tt_id    Term taxonomy ID.
	 * @param string $taxonomy Taxonomy slug.
	 */
	do_action( 'edit_term_taxonomy', $tt_id, $taxonomy );

	$wpdb->update( $wpdb->term_taxonomy, compact( 'term_id', 'taxonomy', 'description', 'parent' ), array( 'term_taxonomy_id' => $tt_id ) );

	/**
	 * Fires immediately after a term-taxonomy relationship is updated.
	 *
	 * @since 2.9.0
	 *
	 * @param int    $tt_id    Term taxonomy ID.
	 * @param string $taxonomy Taxonomy slug.
	 */
	do_action( 'edited_term_taxonomy', $tt_id, $taxonomy );

	/**
	 * Fires after a term has been updated, but before 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( "edit_term", $term_id, $tt_id, $taxonomy );

	/**
	 * Fires after a term in a specific taxonomy has been updated, but before 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( "edit_{$taxonomy}", $term_id, $tt_id );

	/** This filter is documented in wp-includes/taxonomy.php */
	$term_id = apply_filters( 'term_id_filter', $term_id, $tt_id );

	clean_term_cache($term_id, $taxonomy);

	/**
	 * Fires after a term has been updated, and 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( "edited_term", $term_id, $tt_id, $taxonomy );

	/**
	 * Fires after a term for a specific taxonomy has been updated, and 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( "edited_{$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_update_term_data
• wp-includes/taxonomy.php: edit_terms
• wp-includes/taxonomy.php: edited_terms
• wp-includes/l10n.php: __()
• wp-includes/formatting.php: wp_slash()
• wp-includes/formatting.php: wp_unslash()
• wp-includes/formatting.php: sanitize_title()
• wp-includes/functions.php: wp_parse_args()
• 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: wp_update_term_parent
• wp-includes/taxonomy.php: edit_term_taxonomy
• wp-includes/taxonomy.php: edited_term_taxonomy
• wp-includes/taxonomy.php: edit_term
• wp-includes/taxonomy.php: edit_{$taxonomy}
• wp-includes/taxonomy.php: edited_term
• wp-includes/taxonomy.php: edited_{$taxonomy}
• wp-includes/taxonomy.php: term_id_filter
• wp-includes/taxonomy.php: sanitize_term()
• wp-includes/taxonomy.php: term_exists()
• wp-includes/taxonomy.php: get_term_by()
• wp-includes/taxonomy.php: taxonomy_exists()
• wp-includes/taxonomy.php: get_term()
• 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::update()
• wp-includes/wp-db.php: wpdb::prepare()
• wp-includes/load.php: is_wp_error()
• wp-includes/class-wp-error.php: WP_Error::__construct()
Show 26 more uses Hide more uses

---

Used By

• wp-includes/rest-api/endpoints/class-wp-rest-terms-controller.php: WP_REST_Terms_Controller::update_item()
• wp-admin/includes/taxonomy.php: wp_insert_category()
• wp-admin/includes/ajax-actions.php: wp_ajax_inline_save_tax()
• wp-includes/taxonomy.php: wp_check_term_hierarchy_for_loops()
• wp-includes/taxonomy.php: wp_update_term()
• wp-includes/taxonomy.php: wp_insert_term()
• wp-includes/nav-menu.php: wp_update_nav_menu_object()
• wp-includes/class-wp-xmlrpc-server.php: wp_xmlrpc_server::wp_editTerm()
Show 3 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: 0You must log in to vote on the helpfulness of this note Contributed by Codex

   Rename the ‘Uncategorized’ category in French

   
   $update = wp_update_term( 1, 'category', array(
   	'name' => 'Non Catégorisé',
   	'slug' => 'non-categorise'
   ) );
   
   if ( ! is_wp_error( $update ) ) {
   	echo 'Success!';
   }