wp_update_term

Update term based on arguments provided.

Description

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

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.

Returns (array|WP_Error)

Returns Term ID and Taxonomy Term ID

Parameters (3)

0. $term_id (int)
The ID of the term
1. $taxonomy (string)
The context in which to relate the term to the object.
2. $args — Optional. (array) => array()
Array of get_terms() arguments. Default empty array.

Usage

  1. if ( !function_exists( 'wp_update_term' ) ) { 
  2. require_once ABSPATH . WPINC . '/taxonomy.php'; 
  3.  
  4. // The ID of the term 
  5. $term_id = -1; 
  6.  
  7. // The context in which to relate the term to the object. 
  8. $taxonomy = ''; 
  9.  
  10. // Optional. Array of get_terms() arguments. Default empty array. 
  11. $args = array(); 
  12.  
  13. // NOTICE! Understand what this does before running. 
  14. $result = wp_update_term($term_id, $taxonomy, $args); 
  15.  

Defined (1)

The function is defined in the following location(s).

/wp-includes/taxonomy.php  
  1. function wp_update_term( $term_id, $taxonomy, $args = array() ) { 
  2. global $wpdb; 
  3.  
  4. if ( ! taxonomy_exists( $taxonomy ) ) { 
  5. return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) ); 
  6.  
  7. $term_id = (int) $term_id; 
  8.  
  9. // First, get all of the original args 
  10. $term = get_term( $term_id, $taxonomy ); 
  11.  
  12. if ( is_wp_error( $term ) ) { 
  13. return $term; 
  14.  
  15. if ( ! $term ) { 
  16. return new WP_Error( 'invalid_term', __( 'Empty Term' ) ); 
  17.  
  18. $term = (array) $term->data; 
  19.  
  20. // Escape data pulled from DB. 
  21. $term = wp_slash( $term ); 
  22.  
  23. // Merge old and new args with new args overwriting old ones. 
  24. $args = array_merge($term, $args); 
  25.  
  26. $defaults = array( 'alias_of' => '', 'description' => '', 'parent' => 0, 'slug' => ''); 
  27. $args = wp_parse_args($args, $defaults); 
  28. $args = sanitize_term($args, $taxonomy, 'db'); 
  29. $parsed_args = $args; 
  30.  
  31. // expected_slashed ($name) 
  32. $name = wp_unslash( $args['name'] ); 
  33. $description = wp_unslash( $args['description'] ); 
  34.  
  35. $parsed_args['name'] = $name; 
  36. $parsed_args['description'] = $description; 
  37.  
  38. if ( '' == trim( $name ) ) { 
  39. return new WP_Error( 'empty_term_name', __( 'A name is required for this term.' ) ); 
  40.  
  41. if ( $parsed_args['parent'] > 0 && ! term_exists( (int) $parsed_args['parent'] ) ) { 
  42. return new WP_Error( 'missing_parent', __( 'Parent term does not exist.' ) ); 
  43.  
  44. $empty_slug = false; 
  45. if ( empty( $args['slug'] ) ) { 
  46. $empty_slug = true; 
  47. $slug = sanitize_title($name); 
  48. } else { 
  49. $slug = $args['slug']; 
  50.  
  51. $parsed_args['slug'] = $slug; 
  52.  
  53. $term_group = isset( $parsed_args['term_group'] ) ? $parsed_args['term_group'] : 0; 
  54. if ( $args['alias_of'] ) { 
  55. $alias = get_term_by( 'slug', $args['alias_of'], $taxonomy ); 
  56. if ( ! empty( $alias->term_group ) ) { 
  57. // The alias we want is already in a group, so let's use that one. 
  58. $term_group = $alias->term_group; 
  59. } elseif ( ! empty( $alias->term_id ) ) { 
  60. /** 
  61. * The alias is not in a group, so we create a new one 
  62. * and add the alias to it. 
  63. */ 
  64. $term_group = $wpdb->get_var("SELECT MAX(term_group) FROM $wpdb->terms") + 1; 
  65.  
  66. wp_update_term( $alias->term_id, $taxonomy, array( 
  67. 'term_group' => $term_group,  
  68. ) ); 
  69.  
  70. $parsed_args['term_group'] = $term_group; 
  71.  
  72. /** 
  73. * Filters the term parent. 
  74. * Hook to this filter to see if it will cause a hierarchy loop. 
  75. * @since 3.1.0 
  76. * @param int $parent ID of the parent term. 
  77. * @param int $term_id Term ID. 
  78. * @param string $taxonomy Taxonomy slug. 
  79. * @param array $parsed_args An array of potentially altered update arguments for the given term. 
  80. * @param array $args An array of update arguments for the given term. 
  81. */ 
  82. $parent = apply_filters( 'wp_update_term_parent', $args['parent'], $term_id, $taxonomy, $parsed_args, $args ); 
  83.  
  84. // Check for duplicate slug 
  85. $duplicate = get_term_by( 'slug', $slug, $taxonomy ); 
  86. if ( $duplicate && $duplicate->term_id != $term_id ) { 
  87. // If an empty slug was passed or the parent changed, reset the slug to something unique. 
  88. // Otherwise, bail. 
  89. if ( $empty_slug || ( $parent != $term['parent']) ) { 
  90. $slug = wp_unique_term_slug($slug, (object) $args); 
  91. } else { 
  92. /** translators: 1: Taxonomy term slug */ 
  93. return new WP_Error('duplicate_term_slug', sprintf(__('The slug “%s” is already in use by another term'), $slug)); 
  94.  
  95. $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) ); 
  96.  
  97. // Check whether this is a shared term that needs splitting. 
  98. $_term_id = _split_shared_term( $term_id, $tt_id ); 
  99. if ( ! is_wp_error( $_term_id ) ) { 
  100. $term_id = $_term_id; 
  101.  
  102. /** 
  103. * Fires immediately before the given terms are edited. 
  104. * @since 2.9.0 
  105. * @param int $term_id Term ID. 
  106. * @param string $taxonomy Taxonomy slug. 
  107. */ 
  108. do_action( 'edit_terms', $term_id, $taxonomy ); 
  109.  
  110. $data = compact( 'name', 'slug', 'term_group' ); 
  111.  
  112. /** 
  113. * Filters term data before it is updated in the database. 
  114. * @since 4.7.0 
  115. * @param array $data Term data to be updated. 
  116. * @param int $term_id Term ID. 
  117. * @param string $taxonomy Taxonomy slug. 
  118. * @param array $args Arguments passed to wp_update_term(). 
  119. */ 
  120. $data = apply_filters( 'wp_update_term_data', $data, $term_id, $taxonomy, $args ); 
  121.  
  122. $wpdb->update( $wpdb->terms, $data, compact( 'term_id' ) ); 
  123. if ( empty($slug) ) { 
  124. $slug = sanitize_title($name, $term_id); 
  125. $wpdb->update( $wpdb->terms, compact( 'slug' ), compact( 'term_id' ) ); 
  126.  
  127. /** 
  128. * Fires immediately after the given terms are edited. 
  129. * @since 2.9.0 
  130. * @param int $term_id Term ID 
  131. * @param string $taxonomy Taxonomy slug. 
  132. */ 
  133. do_action( 'edited_terms', $term_id, $taxonomy ); 
  134.  
  135. /** 
  136. * Fires immediate before a term-taxonomy relationship is updated. 
  137. * @since 2.9.0 
  138. * @param int $tt_id Term taxonomy ID. 
  139. * @param string $taxonomy Taxonomy slug. 
  140. */ 
  141. do_action( 'edit_term_taxonomy', $tt_id, $taxonomy ); 
  142.  
  143. $wpdb->update( $wpdb->term_taxonomy, compact( 'term_id', 'taxonomy', 'description', 'parent' ), array( 'term_taxonomy_id' => $tt_id ) ); 
  144.  
  145. /** 
  146. * Fires immediately after a term-taxonomy relationship is updated. 
  147. * @since 2.9.0 
  148. * @param int $tt_id Term taxonomy ID. 
  149. * @param string $taxonomy Taxonomy slug. 
  150. */ 
  151. do_action( 'edited_term_taxonomy', $tt_id, $taxonomy ); 
  152.  
  153. /** 
  154. * Fires after a term has been updated, but before the term cache has been cleaned. 
  155. * @since 2.3.0 
  156. * @param int $term_id Term ID. 
  157. * @param int $tt_id Term taxonomy ID. 
  158. * @param string $taxonomy Taxonomy slug. 
  159. */ 
  160. do_action( "edit_term", $term_id, $tt_id, $taxonomy ); 
  161.  
  162. /** 
  163. * Fires after a term in a specific taxonomy has been updated, but before the term 
  164. * cache has been cleaned. 
  165. * The dynamic portion of the hook name, `$taxonomy`, refers to the taxonomy slug. 
  166. * @since 2.3.0 
  167. * @param int $term_id Term ID. 
  168. * @param int $tt_id Term taxonomy ID. 
  169. */ 
  170. do_action( "edit_{$taxonomy}", $term_id, $tt_id ); 
  171.  
  172. /** This filter is documented in wp-includes/taxonomy.php */ 
  173. $term_id = apply_filters( 'term_id_filter', $term_id, $tt_id ); 
  174.  
  175. clean_term_cache($term_id, $taxonomy); 
  176.  
  177. /** 
  178. * Fires after a term has been updated, and the term cache has been cleaned. 
  179. * @since 2.3.0 
  180. * @param int $term_id Term ID. 
  181. * @param int $tt_id Term taxonomy ID. 
  182. * @param string $taxonomy Taxonomy slug. 
  183. */ 
  184. do_action( "edited_term", $term_id, $tt_id, $taxonomy ); 
  185.  
  186. /** 
  187. * Fires after a term for a specific taxonomy has been updated, and the term 
  188. * cache has been cleaned. 
  189. * The dynamic portion of the hook name, `$taxonomy`, refers to the taxonomy slug. 
  190. * @since 2.3.0 
  191. * @param int $term_id Term ID. 
  192. * @param int $tt_id Term taxonomy ID. 
  193. */ 
  194. do_action( "edited_{$taxonomy}", $term_id, $tt_id ); 
  195.  
  196. return array('term_id' => $term_id, 'term_taxonomy_id' => $tt_id);