wp_set_post_terms() – Function | Developer.WordPress.org

Sets the terms for a post.

Description

Parameters

$post_idintoptional: The Post ID. Does not default to the ID of the global $post.
$termsstring|arrayoptional: An array of terms to set for the post, or a string of terms separated by commas. Hierarchical taxonomies must always pass IDs rather than names so that children with the same names but different parents aren’t confused.
Default:''
$taxonomystringoptional: Taxonomy name. Default 'post_tag'.
Default:'post_tag'
$appendbooloptional: If true, don’t delete existing terms, just add on. If false, replace the terms with the new terms.
Default:false

Return

array|false|WP_Error Array of term taxonomy IDs of affected terms. WP_Error or false on failure.

Source

function wp_set_post_terms( $post_id = 0, $terms = '', $taxonomy = 'post_tag', $append = false ) {
	$post_id = (int) $post_id;

	if ( ! $post_id ) {
		return false;
	}

	if ( empty( $terms ) ) {
		$terms = array();
	}

	if ( ! is_array( $terms ) ) {
		$comma = _x( ',', 'tag delimiter' );
		if ( ',' !== $comma ) {
			$terms = str_replace( $comma, ',', $terms );
		}
		$terms = explode( ',', trim( $terms, " \n\t\r\0\x0B," ) );
	}

	/*
	 * Hierarchical taxonomies must always pass IDs rather than names so that
	 * children with the same names but different parents aren't confused.
	 */
	if ( is_taxonomy_hierarchical( $taxonomy ) ) {
		$terms = array_unique( array_map( 'intval', $terms ) );
	}

	return wp_set_object_terms( $post_id, $terms, $taxonomy, $append );
}

View all references View on Trac View on GitHub

Uses	Description
is_taxonomy_hierarchical()`wp-includes/taxonomy.php`	Determines whether the taxonomy object is hierarchical.
wp_set_object_terms()`wp-includes/taxonomy.php`	Creates term and taxonomy relationships.
_x()`wp-includes/l10n.php`	Retrieves translated string with gettext context.

Show 1 more Show less

Used by	Description
wp_set_unique_slug_on_create_template_part()`wp-includes/theme-templates.php`	Sets a custom slug when creating auto-draft template parts.
wp_publish_post()`wp-includes/post.php`	Publishes a post by transitioning the post status.
wp_set_post_tags()`wp-includes/post.php`	Sets the tags for a post.
wp_set_post_categories()`wp-includes/post.php`	Sets categories for a post.
wp_insert_post()`wp-includes/post.php`	Inserts or update a post.
set_post_format()`wp-includes/post-formats.php`	Assign a format to a post

Show 1 more Show less

Changelog

Version	Description
2.8.0	Introduced.

User Contributed Notes

Skip to note 4 content

Codex 9 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 19You must log in to vote on the helpfulness of this note
Non hierarchical term example

For non-hierarchical terms (such as tags), you can pass either the term name or id. If you pass the id there is only one caveat: You must pass it as an integer, and it must be in an array. This is necessary because any non-array value passed will be converted to a string, which will be interpreted as a term name.
```
$tag = '5'; // Wrong. This will add the tag with the *name* '5'.
$tag = 5; // Wrong. This will also add the tag with the name '5'.
$tag = array( '5' ); // Wrong. Again, this will be interpreted as a term name rather than an id.

$tag = array( 5 ); // Correct. This will add the tag with the id 5.
wp_set_post_terms( $post_id, $tag, $taxonomy );
```
This function will only work on the native post type. For a taxonomy on a custom post type use wp_set_object_terms()
Log in to add feedback

stalkerxxl 3 years ago

I do not know why, but you need to wrap your term_id in Array ((int) $ Term_id) – Then it will work as id … otherwise it is to create a term with name = $ Term_id

$exchange = term_exists( $this->response['exchangeShortName'], 'exchange' );

if ( ! $exchange ) {
    $exchange = wp_insert_term( $this->response['exchange'], 'exchange', array( 'slug' => $this->response['exchangeShortName'] ) );
}

// create new term with name = $exchange['term_id'] - BUG?
wp_set_post_terms( $this->postID, array( $exchange['term_id'] ), 'exchange', false ); 

// It works fine, does not create a new term, and simply attaches the existing ID
wp_set_post_terms( $this->postID, array( (int) $exchange['term_id'] ), 'exchange', false );

Skip to note 6 content

Codex 9 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note
Hierarchical term example

For hierarchical terms (such as categories), you must always pass the id rather than the term name to avoid confusion where there may be another child with the same name.

To get the term id you can use:
```
$term_id = term_exists( $term, $taxonomy, $parent );
```
You may also need to pass by reference:
```
wp_set_post_terms( $post_id, $term, &$taxonomy );
```
- Should the last line be: wp_set_post_terms( $post_id, $term_id, $taxonomy ); To show you are passing the term ID from line above. Also term_exists will return an array so you need to specify the ID as specified in term_exists examples. And the ampersand seems like a typo.
  
  Norm 4 years ago
Log in to add feedback

wp_set_post_terms( int $post_id, string|array $terms = ”, string $taxonomy = ‘post_tag’, bool $append = false ): array|false|WP_Error

In this article