wp_set_object_terms

Create Term and Taxonomy Relationships.

Description

(array|WP_Error) wp_set_object_terms( (int) $object_id, (array|int|string) $terms, (string) $taxonomy, (bool) $append = false ); 

Relates an object (post, link etc) to a term and taxonomy type. Creates the term and taxonomy relationship if it doesn't already exist. Creates a term if it doesn't exist (using the slug).

A relationship means that the term is grouped in or belongs to the taxonomy. A term has no meaning until it is given context by defining which taxonomy it exists under.

Returns (array|WP_Error)

Term taxonomy IDs of the affected terms.

Parameters (4)

0. $object_id (int)
The object to relate to.
1. $terms (array|int|string)
A single term slug, single term id, or array of either term slugs or ids. Will replace all existing related terms in this taxonomy.
2. $taxonomy (string)
The context in which to relate the term to the object.
3. $append — Optional. (bool) => false
If false will delete difference of terms. Default false.

Usage

  1. if ( !function_exists( 'wp_set_object_terms' ) ) { 
  2. require_once ABSPATH . WPINC . '/taxonomy.php'; 
  3.  
  4. // The object to relate to. 
  5. $object_id = -1; 
  6.  
  7. // A single term slug, single term id, or array of either term slugs or ids. 
  8. // Will replace all existing related terms in this taxonomy. 
  9. $terms = null; 
  10.  
  11. // The context in which to relate the term to the object. 
  12. $taxonomy = ''; 
  13.  
  14. // Optional. If false will delete difference of terms. Default false. 
  15. $append = false; 
  16.  
  17. // NOTICE! Understand what this does before running. 
  18. $result = wp_set_object_terms($object_id, $terms, $taxonomy, $append); 
  19.  

Defined (1)

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

/wp-includes/taxonomy.php  
  1. function wp_set_object_terms( $object_id, $terms, $taxonomy, $append = false ) { 
  2. global $wpdb; 
  3.  
  4. $object_id = (int) $object_id; 
  5.  
  6. if ( ! taxonomy_exists( $taxonomy ) ) { 
  7. return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) ); 
  8.  
  9. if ( !is_array($terms) ) 
  10. $terms = array($terms); 
  11.  
  12. if ( ! $append ) 
  13. $old_tt_ids = wp_get_object_terms($object_id, $taxonomy, array('fields' => 'tt_ids', 'orderby' => 'none')); 
  14. else 
  15. $old_tt_ids = array(); 
  16.  
  17. $tt_ids = array(); 
  18. $term_ids = array(); 
  19. $new_tt_ids = array(); 
  20.  
  21. foreach ( (array) $terms as $term) { 
  22. if ( !strlen(trim($term)) ) 
  23. continue; 
  24.  
  25. if ( !$term_info = term_exists($term, $taxonomy) ) { 
  26. // Skip if a non-existent term ID is passed. 
  27. if ( is_int($term) ) 
  28. continue; 
  29. $term_info = wp_insert_term($term, $taxonomy); 
  30. if ( is_wp_error($term_info) ) 
  31. return $term_info; 
  32. $term_ids[] = $term_info['term_id']; 
  33. $tt_id = $term_info['term_taxonomy_id']; 
  34. $tt_ids[] = $tt_id; 
  35.  
  36. if ( $wpdb->get_var( $wpdb->prepare( "SELECT term_taxonomy_id FROM $wpdb->term_relationships WHERE object_id = %d AND term_taxonomy_id = %d", $object_id, $tt_id ) ) ) 
  37. continue; 
  38.  
  39. /** 
  40. * Fires immediately before an object-term relationship is added. 
  41. * @since 2.9.0 
  42. * @since 4.7.0 Added the `$taxonomy` parameter. 
  43. * @param int $object_id Object ID. 
  44. * @param int $tt_id Term taxonomy ID. 
  45. * @param string $taxonomy Taxonomy slug. 
  46. */ 
  47. do_action( 'add_term_relationship', $object_id, $tt_id, $taxonomy ); 
  48. $wpdb->insert( $wpdb->term_relationships, array( 'object_id' => $object_id, 'term_taxonomy_id' => $tt_id ) ); 
  49.  
  50. /** 
  51. * Fires immediately after an object-term relationship is added. 
  52. * @since 2.9.0 
  53. * @since 4.7.0 Added the `$taxonomy` parameter. 
  54. * @param int $object_id Object ID. 
  55. * @param int $tt_id Term taxonomy ID. 
  56. * @param string $taxonomy Taxonomy slug. 
  57. */ 
  58. do_action( 'added_term_relationship', $object_id, $tt_id, $taxonomy ); 
  59. $new_tt_ids[] = $tt_id; 
  60.  
  61. if ( $new_tt_ids ) 
  62. wp_update_term_count( $new_tt_ids, $taxonomy ); 
  63.  
  64. if ( ! $append ) { 
  65. $delete_tt_ids = array_diff( $old_tt_ids, $tt_ids ); 
  66.  
  67. if ( $delete_tt_ids ) { 
  68. $in_delete_tt_ids = "'" . implode( "', '", $delete_tt_ids ) . "'"; 
  69. $delete_term_ids = $wpdb->get_col( $wpdb->prepare( "SELECT tt.term_id FROM $wpdb->term_taxonomy AS tt WHERE tt.taxonomy = %s AND tt.term_taxonomy_id IN ($in_delete_tt_ids)", $taxonomy ) ); 
  70. $delete_term_ids = array_map( 'intval', $delete_term_ids ); 
  71.  
  72. $remove = wp_remove_object_terms( $object_id, $delete_term_ids, $taxonomy ); 
  73. if ( is_wp_error( $remove ) ) { 
  74. return $remove; 
  75.  
  76. $t = get_taxonomy($taxonomy); 
  77. if ( ! $append && isset($t->sort) && $t->sort ) { 
  78. $values = array(); 
  79. $term_order = 0; 
  80. $final_tt_ids = wp_get_object_terms($object_id, $taxonomy, array('fields' => 'tt_ids')); 
  81. foreach ( $tt_ids as $tt_id ) 
  82. if ( in_array($tt_id, $final_tt_ids) ) 
  83. $values[] = $wpdb->prepare( "(%d, %d, %d)", $object_id, $tt_id, ++$term_order); 
  84. if ( $values ) 
  85. if ( false === $wpdb->query( "INSERT INTO $wpdb->term_relationships (object_id, term_taxonomy_id, term_order) VALUES " . join( ', ', $values ) . " ON DUPLICATE KEY UPDATE term_order = VALUES(term_order)" ) ) 
  86. return new WP_Error( 'db_insert_error', __( 'Could not insert term relationship into the database' ), $wpdb->last_error ); 
  87.  
  88. wp_cache_delete( $object_id, $taxonomy . '_relationships' ); 
  89. wp_cache_delete( 'last_changed', 'terms' ); 
  90.  
  91. /** 
  92. * Fires after an object's terms have been set. 
  93. * @since 2.8.0 
  94. * @param int $object_id Object ID. 
  95. * @param array $terms An array of object terms. 
  96. * @param array $tt_ids An array of term taxonomy IDs. 
  97. * @param string $taxonomy Taxonomy slug. 
  98. * @param bool $append Whether to append new terms to the old terms. 
  99. * @param array $old_tt_ids Old array of term taxonomy IDs. 
  100. */ 
  101. do_action( 'set_object_terms', $object_id, $terms, $tt_ids, $taxonomy, $append, $old_tt_ids ); 
  102. return $tt_ids;