wp_set_post_terms() │ WP 2.8.0

Sets the terms for specified post (sets categories for post).

For hierarchical terms, you need to pass the term ID but not term name, otherwise name conflict may be occur: there are may be the same term name in different taxonomy branches.

You can see the term ID in the admin panel (in the edit term URL) or get it like this:

$term_id = term_exists( $term, $taxonomy, $parent )['term_id'];
Uses: wp_set_object_terms()
Used By: wp_set_post_categories(), wp_set_post_tags(), set_post_format()

No Hooks.

Return

Array|false|WP_Error.

  • false — when $post_id isn't number or 0.
  • Array of ID — which was affected.
  • WP_Error — on error.

Usage

wp_set_post_terms( $post_id, $terms, $taxonomy, $append );
$post_ID(int) (required)
Post ID.
$tags(string/array/int[])

A list of taxonomy elements in the form of an array or a comma-separated string.

If the taxonomy is hierarchical, then you should specify term ID only (as a integer)! If you pass string, it will turn to 0. This is necessary because hierarchical taxonomies could have 2 terms with the same name.

Also, It is important to make sure that the IDs passed as 'integer' type, but not 'string'! Because strings in the form of a number, for example, '98' will be interpreted as the name of the term, and not its ID! In the new versions of the engine, this bug seems to have been fixed.

The function will create a new term if it does not find a suitable one. At the same time, if you specify the name in Cyrillic, the name will be as you pass it, but the slug will be processed with sanitize_title() function.

Default: ''

$taxonomy(строка)
The name of the taxonomy to elements of which the posts will be attached.
Default: post_tag
$append(логический)
Add to existing or replace terms:
true — will be added to existing ones;
false — will be replaced.
Default: false

Examples

1. Default categories and tags

The following example shows how to set default Category (cat name) and Tag (tag name) for newly creating post if such category or tag is not yet specified:

The code can be inserted into functions.php.

add_action( 'wp_insert_post', 'update_post_terms' );
function update_post_terms( $post_id ) {
	if ( $parent = wp_is_post_revision( $post_id ) )
		$post_id = $parent;

	$post = get_post( $post_id );

	if ( $post->post_type != 'post' )
		return;

	// add default tag
	wp_set_post_terms( $post_id, 'Tag Name', 'post_tag', true );

	// add default category
	$categories = wp_get_post_categories( $post_id );
	$newcat    = get_term_by( 'name', 'Cat Name', 'category' );
	array_push( $categories, $newcat->term_id );

	wp_set_post_categories( $post_id, $categories );
}
0

#1 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 );

Now use such code:

wp_set_post_terms( $post_id, $term_id, $taxonomy );

Notes

Changelog

Since 2.8.0 Introduced.

wp_set_post_terms() code WP 6.5.2

wp-includes/post.php 
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 );
}

Term (taxonomies terms)

For posts