wp_set_object_terms()
Create Term and Taxonomy Relationships.
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.
Hooks from the function
Return
Array|WP_Error
. Term taxonomy IDs of the affected terms or WP_Error on failure.
Usage
wp_set_object_terms( $object_id, $terms, $taxonomy, $append );
- $object_id(int) (required)
- The object to relate to.
- $terms(string|int|array) (required)
- 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(string) (required)
- The context in which to relate the term to the object.
- $append(true|false)
- If false will delete difference of terms.
Default: false
Examples
#1 Put the post in specified categories
An example showing how to add post 42 to categories 6 and 8:
$cat_ids = array( 6, 8 ); // to make sure the terms are passed as numbers: // $cat_ids = array_map( 'intval', $cat_ids ); wp_set_object_terms( 42, $cat_ids, 'category' );
If term IDs are specified as strings, the function will create categories with those names and attaches the post to the terms.
#2 Delete post from all categories
If you want to remove post 42 from all categories (even the one set by default):
wp_set_object_terms( 42, NULL, 'category' );
#3 Be careful when adding existing terms to object!
The second parameter $terms (eg. category id) needs to be of type integer or array of integers.
Note: If you provide a string value for $terms, WordPress will create a new term named after the $terms value and not pick the existing term by term_id. This happens because the $terms must be integer
or array
of integers.
$post_id = 15; $category_id = '14'; $taxonomy = 'category'; // Wrong: wp_set_object_terms( $post_id, $category_id, $taxonomy ); // Correct: wp_set_object_terms( $post_id, (int) $category_id, $taxonomy );
#4 Create tags and put the post in them
This example puts post 54 into the tags tag1
and tag2
if there are no such tags they will be created:
wp_set_object_terms( 54, [ 'tag1', 'tag2' ], 'post_tag' );
#5 A stricter function for setting terms for a post
To avoid worrying that the current function may create a term if it doesn't exist and that it is mandatory to specify the taxonomy, even if we are passing term IDs.
All this magic only complicates the code. Therefore, in one of my projects, I wrote the following function, which is easier and clearer to work with.
This function requires you to pass the post ID and the term(s) ID to which we want to attach the post. There is no need to specify the taxonomy. If the specified term does not exist, the function will simply skip it, creating nothing. If term IDs from different taxonomies are specified, you will receive an error.
/** * Sets specified terms for the specified posts. * Wrapper for wp_set_object_terms() with strict behavior, requiring term IDs only. * * @param int $post_id * @param int[]|int $term_ids * @param bool $append * * @return int[]|WP_Error */ function strict_set_post_terms( $post_id, $term_ids, $append = true ){ $post_id = (int) $post_id; $term_ids = array_filter( array_map( 'intval', (array) $term_ids ) ); if( ! $post_id ){ return new WP_Error( 'error', 'Invalid or missing post ID.' ); } if( ! $term_ids ){ return new WP_Error( 'error', 'No valid term IDs provided.' ); } $taxonomy = ''; // check terms foreach( $term_ids as $index => $term_id ){ $term = get_term( $term_id ); if( ! $term ){ unset( $term_ids[ $index ] ); continue; // skip invalid terms } if( $taxonomy && $taxonomy !== $term->taxonomy ){ return new WP_Error( 'error', 'Terms from different taxonomies specified.' ); } $taxonomy = $term->taxonomy; } if( ! $term_ids ){ return new WP_Error( 'error', 'No valid term IDs provided.' ); } $result = wp_set_object_terms( $post_id, $term_ids, $taxonomy, $append ); if( ! is_wp_error( $result ) ){ $result = array_map( 'intval', $result ); } return $result; }
Notes
- Global. wpdb. $wpdb WordPress database abstraction object.
Changelog
Since 2.3.0 | Introduced. |