_split_shared_term

Create a new term for a term_taxonomy item that currently shares its term with another term_taxonomy.

Description

(int|WP_Error) _split_shared_term( (int|object) $term_id, (int|object) $term_taxonomy_id, (bool) $record = true ); 

Returns (int|WP_Error)

When the current term does not need to be split (or cannot be split on the current database schema), `$term_id` is returned. When the term is successfully split, the new term_id is returned. A WP_Error is returned for miscellaneous errors.

Parameters (3)

0. $term_id (int|object)
ID of the shared term, or the shared term object.
1. $term_taxonomy_id (int|object)
ID of the term_taxonomy item to receive a new term, or the term_taxonomy object (corresponding to a row from the term_taxonomy table).
2. $record — Optional. (bool) => true
Whether to record data about the split term in the options table. The recording process has the potential to be resource-intensive, so during batch operations it can be beneficial to skip inline recording and do it just once, after the batch is processed. Only set this to false if you know what you are doing. Default: true.

Usage

  1. if ( !function_exists( '_split_shared_term' ) ) { 
  2. require_once ABSPATH . WPINC . '/taxonomy.php'; 
  3.  
  4. // ID of the shared term, or the shared term object. 
  5. $term_id = null; 
  6.  
  7. // ID of the term_taxonomy item to receive a new term, or the term_taxonomy object 
  8. // (corresponding to a row from the term_taxonomy table). 
  9. $term_taxonomy_id = null; 
  10. $record = true; 
  11.  
  12. // NOTICE! Understand what this does before running. 
  13. $result = _split_shared_term($term_id, $term_taxonomy_id, $record); 
  14.  

Defined (1)

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

/wp-includes/taxonomy.php  
  1. function _split_shared_term( $term_id, $term_taxonomy_id, $record = true ) { 
  2. global $wpdb; 
  3.  
  4. if ( is_object( $term_id ) ) { 
  5. $shared_term = $term_id; 
  6. $term_id = intval( $shared_term->term_id ); 
  7.  
  8. if ( is_object( $term_taxonomy_id ) ) { 
  9. $term_taxonomy = $term_taxonomy_id; 
  10. $term_taxonomy_id = intval( $term_taxonomy->term_taxonomy_id ); 
  11.  
  12. // If there are no shared term_taxonomy rows, there's nothing to do here. 
  13. $shared_tt_count = $wpdb->get_var( $wpdb->prepare( "SELECT COUNT(*) FROM $wpdb->term_taxonomy tt WHERE tt.term_id = %d AND tt.term_taxonomy_id != %d", $term_id, $term_taxonomy_id ) ); 
  14.  
  15. if ( ! $shared_tt_count ) { 
  16. return $term_id; 
  17.  
  18. /** 
  19. * Verify that the term_taxonomy_id passed to the function is actually associated with the term_id. 
  20. * If there's a mismatch, it may mean that the term is already split. Return the actual term_id from the db. 
  21. */ 
  22. $check_term_id = $wpdb->get_var( $wpdb->prepare( "SELECT term_id FROM $wpdb->term_taxonomy WHERE term_taxonomy_id = %d", $term_taxonomy_id ) ); 
  23. if ( $check_term_id != $term_id ) { 
  24. return $check_term_id; 
  25.  
  26. // Pull up data about the currently shared slug, which we'll use to populate the new one. 
  27. if ( empty( $shared_term ) ) { 
  28. $shared_term = $wpdb->get_row( $wpdb->prepare( "SELECT t.* FROM $wpdb->terms t WHERE t.term_id = %d", $term_id ) ); 
  29.  
  30. $new_term_data = array( 
  31. 'name' => $shared_term->name,  
  32. 'slug' => $shared_term->slug,  
  33. 'term_group' => $shared_term->term_group,  
  34. ); 
  35.  
  36. if ( false === $wpdb->insert( $wpdb->terms, $new_term_data ) ) { 
  37. return new WP_Error( 'db_insert_error', __( 'Could not split shared term.' ), $wpdb->last_error ); 
  38.  
  39. $new_term_id = (int) $wpdb->insert_id; 
  40.  
  41. // Update the existing term_taxonomy to point to the newly created term. 
  42. $wpdb->update( $wpdb->term_taxonomy,  
  43. array( 'term_id' => $new_term_id ),  
  44. array( 'term_taxonomy_id' => $term_taxonomy_id ) 
  45. ); 
  46.  
  47. // Reassign child terms to the new parent. 
  48. if ( empty( $term_taxonomy ) ) { 
  49. $term_taxonomy = $wpdb->get_row( $wpdb->prepare( "SELECT * FROM $wpdb->term_taxonomy WHERE term_taxonomy_id = %d", $term_taxonomy_id ) ); 
  50.  
  51. $children_tt_ids = $wpdb->get_col( $wpdb->prepare( "SELECT term_taxonomy_id FROM $wpdb->term_taxonomy WHERE parent = %d AND taxonomy = %s", $term_id, $term_taxonomy->taxonomy ) ); 
  52. if ( ! empty( $children_tt_ids ) ) { 
  53. foreach ( $children_tt_ids as $child_tt_id ) { 
  54. $wpdb->update( $wpdb->term_taxonomy,  
  55. array( 'parent' => $new_term_id ),  
  56. array( 'term_taxonomy_id' => $child_tt_id ) 
  57. ); 
  58. clean_term_cache( $term_id, $term_taxonomy->taxonomy ); 
  59. } else { 
  60. // If the term has no children, we must force its taxonomy cache to be rebuilt separately. 
  61. clean_term_cache( $new_term_id, $term_taxonomy->taxonomy ); 
  62.  
  63. // Clean the cache for term taxonomies formerly shared with the current term. 
  64. $shared_term_taxonomies = $wpdb->get_row( $wpdb->prepare( "SELECT taxonomy FROM $wpdb->term_taxonomy WHERE term_id = %d", $term_id ) ); 
  65. if ( $shared_term_taxonomies ) { 
  66. foreach ( $shared_term_taxonomies as $shared_term_taxonomy ) { 
  67. clean_term_cache( $term_id, $shared_term_taxonomy ); 
  68.  
  69. // Keep a record of term_ids that have been split, keyed by old term_id. See wp_get_split_term(). 
  70. if ( $record ) { 
  71. $split_term_data = get_option( '_split_terms', array() ); 
  72. if ( ! isset( $split_term_data[ $term_id ] ) ) { 
  73. $split_term_data[ $term_id ] = array(); 
  74.  
  75. $split_term_data[ $term_id ][ $term_taxonomy->taxonomy ] = $new_term_id; 
  76. update_option( '_split_terms', $split_term_data ); 
  77.  
  78. // If we've just split the final shared term, set the "finished" flag. 
  79. $shared_terms_exist = $wpdb->get_results( 
  80. "SELECT tt.term_id, t.*, count(*) as term_tt_count FROM {$wpdb->term_taxonomy} tt 
  81. LEFT JOIN {$wpdb->terms} t ON t.term_id = tt.term_id 
  82. GROUP BY t.term_id 
  83. HAVING term_tt_count > 1 
  84. LIMIT 1" 
  85. ); 
  86. if ( ! $shared_terms_exist ) { 
  87. update_option( 'finished_splitting_shared_terms', true ); 
  88.  
  89. /** 
  90. * Fires after a previously shared taxonomy term is split into two separate terms. 
  91. * @since 4.2.0 
  92. * @param int $term_id ID of the formerly shared term. 
  93. * @param int $new_term_id ID of the new term created for the $term_taxonomy_id. 
  94. * @param int $term_taxonomy_id ID for the term_taxonomy row affected by the split. 
  95. * @param string $taxonomy Taxonomy for the split term. 
  96. */ 
  97. do_action( 'split_shared_term', $term_id, $new_term_id, $term_taxonomy_id, $term_taxonomy->taxonomy ); 
  98.  
  99. return $new_term_id;