WordPress.org

Ready to get started?Download WordPress

Codex

Function Reference/wp set object terms

Contents

Description

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

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.

Usage

 <?php wp_set_object_terms$object_id$terms$taxonomy$append ); ?> 

Parameters

$object_id
(int) (required) The object to relate to, such as post ID.
Default: None
$terms
(array/int/string) (required) The slug or id of the term (such as category or tag IDs), will replace all existing related terms in this taxonomy. To clear or remove all terms from an object, pass an empty string or NULL. Integers are interpreted as tag IDs. Warning: some functions may return term_ids as strings which will be interpreted as slugs consisting of numeric characters!
Default: None
$taxonomy
(array/string) (required) The context in which to relate the term to the object. This can be category, post_tag, or the name of another taxonomy.
Default: None
$append
(bool) (optional) If true, tags will be appended to the object. If false, tags will replace existing tags
Default: False

Returns

(mixed) 
  • (array) An array of the terms ( as term_taxonomy_ids ! ) affected if successful,
  • (WP_Error) The WordPress Error object on invalid taxonomy ('invalid_taxonomy').
  • (string) The first offending term if a term given in the $terms parameter is named incorrectly. (Invalid term ids are accepted and inserted).

Hooks


Examples

Setting a Post's Categories

If you want to set the categories of a post with the ID of 42:

<?php

// An array of IDs of categories we want this post to have.
$cat_ids = array( 6, 8 );

/*
 * If this was coming from the database or another source, we would need to make sure
 * these where integers:

$cat_ids = array_map( 'intval', $cat_ids );
$cat_ids = array_unique( $cat_ids );

 */

$term_taxonomy_ids = wp_set_object_terms( 42, $cat_ids, 'category' );

if ( is_wp_error( $term_taxonomy_ids ) ) {
	// There was an error somewhere and the terms couldn't be set.
} else {
	// Success! The post's categories were set.
}

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.

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:

<?php

// An array of IDs of categories we to add to this post.
$cat_ids = array( 6, 8 );

/*
 * If this was coming from the database or another source, we would need to make sure
 * these where integers:

$cat_ids = array_map( 'intval', $cat_ids );
$cat_ids = array_unique( $cat_ids );

 */

// Add these categories, note the last argument is true.
$term_taxonomy_ids = wp_set_object_terms( 42, $cat_ids, 'category', true );

if ( is_wp_error( $term_taxonomy_ids ) ) {
	// There was an error somewhere and the terms couldn't be set.
} else {
	// Success! These categories were added to the post.
}

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:

<?php wp_set_object_terms( 42, null, 'category' ); ?>

Change Log

Notes

  • Perhaps the wp_set_post_terms() is a more useful function, since it checks the values​​, converting taxonomies separated by commas and validating hierarchical terms in integers.
  • It may be confusing but the returned array consists of term_taxonomy_ids instead of term_ids.

Source File

wp_set_object_terms() is located in wp-includes/taxonomy.php.

Related

See also index of Function Reference and index of Template Tags.