Creates term and taxonomy relationships.
Description
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.
Parameters
$object_id
intrequired- The object to relate to.
$terms
string|int|arrayrequired- A single term slug, single term ID, or array of either term slugs or IDs.
Will replace all existing related terms in this taxonomy. Passing an empty array will remove all related terms. $taxonomy
stringrequired- The context in which to relate the term to the object.
$append
booloptional- If false will delete difference of terms.
Default:
false
Source
function wp_set_object_terms( $object_id, $terms, $taxonomy, $append = false ) {
global $wpdb;
$object_id = (int) $object_id;
if ( ! taxonomy_exists( $taxonomy ) ) {
return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) );
}
if ( empty( $terms ) ) {
$terms = array();
} elseif ( ! is_array( $terms ) ) {
$terms = array( $terms );
}
if ( ! $append ) {
$old_tt_ids = wp_get_object_terms(
$object_id,
$taxonomy,
array(
'fields' => 'tt_ids',
'orderby' => 'none',
'update_term_meta_cache' => false,
)
);
} else {
$old_tt_ids = array();
}
$tt_ids = array();
$new_tt_ids = array();
foreach ( (array) $terms as $term ) {
if ( '' === trim( $term ) ) {
continue;
}
$term_info = term_exists( $term, $taxonomy );
if ( ! $term_info ) {
// Skip if a non-existent term ID is passed.
if ( is_int( $term ) ) {
continue;
}
$term_info = wp_insert_term( $term, $taxonomy );
}
if ( is_wp_error( $term_info ) ) {
return $term_info;
}
$tt_id = $term_info['term_taxonomy_id'];
$tt_ids[] = $tt_id;
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 ) ) ) {
continue;
}
/**
* Fires immediately before an object-term relationship is added.
*
* @since 2.9.0
* @since 4.7.0 Added the `$taxonomy` parameter.
*
* @param int $object_id Object ID.
* @param int $tt_id Term taxonomy ID.
* @param string $taxonomy Taxonomy slug.
*/
do_action( 'add_term_relationship', $object_id, $tt_id, $taxonomy );
$wpdb->insert(
$wpdb->term_relationships,
array(
'object_id' => $object_id,
'term_taxonomy_id' => $tt_id,
)
);
/**
* Fires immediately after an object-term relationship is added.
*
* @since 2.9.0
* @since 4.7.0 Added the `$taxonomy` parameter.
*
* @param int $object_id Object ID.
* @param int $tt_id Term taxonomy ID.
* @param string $taxonomy Taxonomy slug.
*/
do_action( 'added_term_relationship', $object_id, $tt_id, $taxonomy );
$new_tt_ids[] = $tt_id;
}
if ( $new_tt_ids ) {
wp_update_term_count( $new_tt_ids, $taxonomy );
}
if ( ! $append ) {
$delete_tt_ids = array_diff( $old_tt_ids, $tt_ids );
if ( $delete_tt_ids ) {
$in_delete_tt_ids = "'" . implode( "', '", $delete_tt_ids ) . "'";
$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 ) );
$delete_term_ids = array_map( 'intval', $delete_term_ids );
$remove = wp_remove_object_terms( $object_id, $delete_term_ids, $taxonomy );
if ( is_wp_error( $remove ) ) {
return $remove;
}
}
}
$t = get_taxonomy( $taxonomy );
if ( ! $append && isset( $t->sort ) && $t->sort ) {
$values = array();
$term_order = 0;
$final_tt_ids = wp_get_object_terms(
$object_id,
$taxonomy,
array(
'fields' => 'tt_ids',
'update_term_meta_cache' => false,
)
);
foreach ( $tt_ids as $tt_id ) {
if ( in_array( (int) $tt_id, $final_tt_ids, true ) ) {
$values[] = $wpdb->prepare( '(%d, %d, %d)', $object_id, $tt_id, ++$term_order );
}
}
if ( $values ) {
if ( false === $wpdb->query( "INSERT INTO $wpdb->term_relationships (object_id, term_taxonomy_id, term_order) VALUES " . implode( ',', $values ) . ' ON DUPLICATE KEY UPDATE term_order = VALUES(term_order)' ) ) {
return new WP_Error( 'db_insert_error', __( 'Could not insert term relationship into the database.' ), $wpdb->last_error );
}
}
}
wp_cache_delete( $object_id, $taxonomy . '_relationships' );
wp_cache_set_terms_last_changed();
/**
* Fires after an object's terms have been set.
*
* @since 2.8.0
*
* @param int $object_id Object ID.
* @param array $terms An array of object term IDs or slugs.
* @param array $tt_ids An array of term taxonomy IDs.
* @param string $taxonomy Taxonomy slug.
* @param bool $append Whether to append new terms to the old terms.
* @param array $old_tt_ids Old array of term taxonomy IDs.
*/
do_action( 'set_object_terms', $object_id, $terms, $tt_ids, $taxonomy, $append, $old_tt_ids );
return $tt_ids;
}
Hooks
- do_action( ‘added_term_relationship’,
int $object_id ,int $tt_id ,string $taxonomy ) Fires immediately after an object-term relationship is added.
- do_action( ‘add_term_relationship’,
int $object_id ,int $tt_id ,string $taxonomy ) Fires immediately before an object-term relationship is added.
- do_action( ‘set_object_terms’,
int $object_id ,array $terms ,array $tt_ids ,string $taxonomy ,bool $append ,array $old_tt_ids ) Fires after an object’s terms have been set.
Changelog
Version | Description |
---|---|
2.3.0 | Introduced. |
Be careful when adding existing terms to object!
The second parameter
$terms
(eg. category id) needs to be of typeinteger
orarray of integers
.Note: If you provide a
string
value for$terms
, WordPress will create new term named after the$terms
value and not pick existing term byterm_id
. This happens because the$terms
must beinteger
orarray of integers
.Wrong:
Correct:
With the
intval()
function we cast the second parameter tointeger
. You can also use(int) $category_id
Setting a Post’s Categories
If you want to set the categories of a post with the ID of 42:
Note that this will set a post’s categories to be exactly the array you pass, any categories the post previously had will be removed from the post. See the next example.
Removing All Categories From a Post
If you want to clear/remove all categories from a post, you can pass an empty value for $terms:
I hope this helps someone when using this function with
wp_insert_post()
and/orwp_update_post()
.$post_args = [
'post_title' => $title,
'post_status' => 'publish',
'post_type' => $pt,
'post_content' => $content,
];
$new_post_id = wp_insert_post($post_args);
wp_set_object_terms($new_post_id->ID === null ? $new_post_id : $new_post_id->ID, array(intval($term_id)), $tax);
On post creation –
$new_post_id
exists as an int(id), however, when updating the post,$new_post_id
exists as the post objectTo counteract this
$new_post_id->ID
will fetch the int after post is created, but not before, therefore, using$new_post_id->ID
will not work as it doesn’t exist yetSo set
$new_post_id
first only if$new_post_id->ID
returns null, otherwise use the ID from the objectThis confused me and many many others for ages, so hopefully, this will help someone.
Adding Categories to a Post
If you want to add categories to a post while keeping the categories it has already, you need to pass true for the $append parameter: