WordPress Version: 6.3
/**
* Updates term based on arguments provided.
*
* 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' will be used.
* If you set 'slug' and it isn't unique, then a WP_Error is returned.
* If you don't pass any slug, then a unique one will be created.
*
* @since 2.3.0
*
* @global wpdb $wpdb WordPress database abstraction object.
*
* @param int $term_id The ID of the term.
* @param string $taxonomy The taxonomy of the term.
* @param array $args {
* Optional. Array of arguments for updating a term.
*
* @type string $alias_of Slug of the term to make this term an alias of.
* Default empty string. Accepts a term slug.
* @type string $description The term description. Default empty string.
* @type int $parent The id of the parent term. Default 0.
* @type string $slug The term slug to use. Default empty string.
* }
* @return array|WP_Error An array containing the `term_id` and `term_taxonomy_id`,
* WP_Error otherwise.
*/
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 ((int) $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_term 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 Arguments passed to wp_update_term().
*/
$parent = (int) 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 !== (int) $term['parent']) {
$slug = wp_unique_term_slug($slug, (object) $args);
} else {
/* translators: %s: 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
* @since 6.1.0 The `$args` parameter was added.
*
* @param int $term_id Term ID.
* @param string $taxonomy Taxonomy slug.
* @param array $args Arguments passed to wp_update_term().
*/
do_action('edit_terms', $term_id, $taxonomy, $args);
$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 a term is updated in the database, but before its
* term-taxonomy relationship is updated.
*
* @since 2.9.0
* @since 6.1.0 The `$args` parameter was added.
*
* @param int $term_id Term ID.
* @param string $taxonomy Taxonomy slug.
* @param array $args Arguments passed to wp_update_term().
*/
do_action('edited_terms', $term_id, $taxonomy, $args);
/**
* Fires immediate before a term-taxonomy relationship is updated.
*
* @since 2.9.0
* @since 6.1.0 The `$args` parameter was added.
*
* @param int $tt_id Term taxonomy ID.
* @param string $taxonomy Taxonomy slug.
* @param array $args Arguments passed to wp_update_term().
*/
do_action('edit_term_taxonomy', $tt_id, $taxonomy, $args);
$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
* @since 6.1.0 The `$args` parameter was added.
*
* @param int $tt_id Term taxonomy ID.
* @param string $taxonomy Taxonomy slug.
* @param array $args Arguments passed to wp_update_term().
*/
do_action('edited_term_taxonomy', $tt_id, $taxonomy, $args);
/**
* Fires after a term has been updated, but before the term cache has been cleaned.
*
* The {@see 'edit_$taxonomy'} hook is also available for targeting a specific
* taxonomy.
*
* @since 2.3.0
* @since 6.1.0 The `$args` parameter was added.
*
* @param int $term_id Term ID.
* @param int $tt_id Term taxonomy ID.
* @param string $taxonomy Taxonomy slug.
* @param array $args Arguments passed to wp_update_term().
*/
do_action('edit_term', $term_id, $tt_id, $taxonomy, $args);
/**
* 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.
*
* Possible hook names include:
*
* - `edit_category`
* - `edit_post_tag`
*
* @since 2.3.0
* @since 6.1.0 The `$args` parameter was added.
*
* @param int $term_id Term ID.
* @param int $tt_id Term taxonomy ID.
* @param array $args Arguments passed to wp_update_term().
*/
do_action("edit_{$taxonomy}", $term_id, $tt_id, $args);
/** 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.
*
* The {@see 'edited_$taxonomy'} hook is also available for targeting a specific
* taxonomy.
*
* @since 2.3.0
* @since 6.1.0 The `$args` parameter was added.
*
* @param int $term_id Term ID.
* @param int $tt_id Term taxonomy ID.
* @param string $taxonomy Taxonomy slug.
* @param array $args Arguments passed to wp_update_term().
*/
do_action('edited_term', $term_id, $tt_id, $taxonomy, $args);
/**
* 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.
*
* Possible hook names include:
*
* - `edited_category`
* - `edited_post_tag`
*
* @since 2.3.0
* @since 6.1.0 The `$args` parameter was added.
*
* @param int $term_id Term ID.
* @param int $tt_id Term taxonomy ID.
* @param array $args Arguments passed to wp_update_term().
*/
do_action("edited_{$taxonomy}", $term_id, $tt_id, $args);
/** This action is documented in wp-includes/taxonomy.php */
do_action('saved_term', $term_id, $tt_id, $taxonomy, true, $args);
/** This action is documented in wp-includes/taxonomy.php */
do_action("saved_{$taxonomy}", $term_id, $tt_id, true, $args);
return array('term_id' => $term_id, 'term_taxonomy_id' => $tt_id);
}