Обновляет термин (элемент таксономии), используя указанные данные.
Перед обновлением данных термина эта функция берет исходные данные из БД и обновляет их переданными данными. Любое новое поле, указанное в $args, будет переопределять старое.
Все поля указанные в $args будут пере-записаны в БД. Поэтому внимательно проверьте обновляемые данные, чтобы не изменить что-то лишнее.
Используйте wp_insert_term(), когда нужно добавить новый термин.
Название таксономии к которой принадлежит термин. Например: category, post_tag.
$args(массив)
Массив или строка (в виде аргументов запроса) новых полей термина.
name(строка).
Имя нового термина. По умолчанию: '' - пустая строка.
slug(строка)
Ярлык нового термина.
Если не передали slug, то будет создан уникальный slug. Для его создания будет использован аргумент 'name'.
Если задали `'slug'' и он не уникален, то будет возвращена ошибка WP_Error.
По умолчанию: '' - пустая строка.
description(string).
Описание термина. По умолчанию: '' - пустая строка.
parent(int)
Идентификатор родительского термина.
alias_of(string)
Ярлык термина для размещения текущего термина и указанного в этом параметре термина в одной группе - для обоих терминов будет одинаковое значение в поле 'term_group'.
WP пытается получить термин по указанному здесь slug термина. Затем получает номер его term_group и использует его для текущего термина. Таким образом, эти два термина объединяются в одну группу.
Если поле term_group пусто для указанного здесь термина. Тогда WP берет MAX номер существующей группы терминов из БД, увеличивает его на 1, и использует новый номер term_group для обоих терминов: текущего обновляемого термина и термина указанного в этом параметре.
Пример показывает, как обновить термин 1 в таксономии category (т.е. как обновить рубрику с ID=1).
$result = wp_update_term( 1, 'category', [
'name' => 'Non Categorise',
// 'slug' => 'non-categorise' // this value creates automatically
// specify it only if you need to define some specific slug
] );
// check the result
if( is_wp_error( $result ) ){
echo $result->get_error_message();
}
else {
echo 'Term was successfully updated.';
}
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,
);
}
