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. Function intval() is required in term IDs.
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) (required) If false will delete difference of terms.
Default: False

Returns

(array|WP_Error) 
Affected Term IDs.

Examples

If you wanted to add a categories to a post with the ID of 42: 

<?php
$cat_ids = array( 6,8 );
    //to make sure the terms IDs is integers:
    //$cat_ids = array_map('intval', $cat_ids);
    //$cat_ids = array_unique( $cat_ids );
wp_set_object_terms( '42', $cat_ids, 'category' );
?>

If you wanted to clear/remove all categories from a post with the ID of 42: 

<?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.

Source File

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

Related

wp_set_post_terms() | wp_get_object_terms()


See also index of Function Reference and index of Template Tags.
Retrieved from "http://codex.wordpress.org/Function_Reference/wp_set_object_terms"

Codex Resources