wp_set_object_terms( int $object_id, string|int|array $terms, string $taxonomy, bool $append = false ): array|WP_Error

Creates term and taxonomy relationships.

Description

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.

Parameters

$object_idintrequired
The object to relate to.
$termsstring|int|arrayrequired
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.
$taxonomystringrequired
The context in which to relate the term to the object.
$appendbooloptional
If false will delete difference of terms.

Default:false

Return

array|WP_Error Term taxonomy IDs of the affected terms or WP_Error on failure.

More Information

For parameter $terms, integers are interpreted as tag IDs. Some functions may return term_ids as strings which will be interpreted as slugs consisting of numeric characters.

For Return:

  • (array) An array of the terms ( as term_taxonomy_ids ! ) affected if successful
  • (array) An empty array if the $terms argument was NULL or empty – successmessage for the removing of the term
  • (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).

This function does not check if there is a relationship between the object (=post type) and the taxonomy (like post_tag, category or custom taxonomy). Because of that, any existing term will be paired with the object, whether or not there is a connection between the object and the taxonomy (of this particular term)!! ( Further information in german)

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

function wp_set_object_terms( $object_id, $terms, $taxonomy, $append = false ) {
	global $wpdb;

	$object_id = (int) $object_id;

	if ( ! taxonomy_exists( $taxonomy ) ) {
		return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) );
	}

	if ( empty( $terms ) ) {
		$terms = array();
	} elseif ( ! is_array( $terms ) ) {
		$terms = array( $terms );
	}

	if ( ! $append ) {
		$old_tt_ids = wp_get_object_terms(
			$object_id,
			$taxonomy,
			array(
				'fields'                 => 'tt_ids',
				'orderby'                => 'none',
				'update_term_meta_cache' => false,
			)
		);
	} else {
		$old_tt_ids = array();
	}

	$tt_ids     = array();
	$term_ids   = array();
	$new_tt_ids = array();

	foreach ( (array) $terms as $term ) {
		if ( '' === trim( $term ) ) {
			continue;
		}

		$term_info = term_exists( $term, $taxonomy );

		if ( ! $term_info ) {
			// Skip if a non-existent term ID is passed.
			if ( is_int( $term ) ) {
				continue;
			}

			$term_info = wp_insert_term( $term, $taxonomy );
		}

		if ( is_wp_error( $term_info ) ) {
			return $term_info;
		}

		$term_ids[] = $term_info['term_id'];
		$tt_id      = $term_info['term_taxonomy_id'];
		$tt_ids[]   = $tt_id;

		if ( $wpdb->get_var( $wpdb->prepare( "SELECT term_taxonomy_id FROM $wpdb->term_relationships WHERE object_id = %d AND term_taxonomy_id = %d", $object_id, $tt_id ) ) ) {
			continue;
		}

		/**
		 * Fires immediately before an object-term relationship is added.
		 *
		 * @since 2.9.0
		 * @since 4.7.0 Added the `$taxonomy` parameter.
		 *
		 * @param int    $object_id Object ID.
		 * @param int    $tt_id     Term taxonomy ID.
		 * @param string $taxonomy  Taxonomy slug.
		 */
		do_action( 'add_term_relationship', $object_id, $tt_id, $taxonomy );

		$wpdb->insert(
			$wpdb->term_relationships,
			array(
				'object_id'        => $object_id,
				'term_taxonomy_id' => $tt_id,
			)
		);

		/**
		 * Fires immediately after an object-term relationship is added.
		 *
		 * @since 2.9.0
		 * @since 4.7.0 Added the `$taxonomy` parameter.
		 *
		 * @param int    $object_id Object ID.
		 * @param int    $tt_id     Term taxonomy ID.
		 * @param string $taxonomy  Taxonomy slug.
		 */
		do_action( 'added_term_relationship', $object_id, $tt_id, $taxonomy );

		$new_tt_ids[] = $tt_id;
	}

	if ( $new_tt_ids ) {
		wp_update_term_count( $new_tt_ids, $taxonomy );
	}

	if ( ! $append ) {
		$delete_tt_ids = array_diff( $old_tt_ids, $tt_ids );

		if ( $delete_tt_ids ) {
			$in_delete_tt_ids = "'" . implode( "', '", $delete_tt_ids ) . "'";
			$delete_term_ids  = $wpdb->get_col( $wpdb->prepare( "SELECT tt.term_id FROM $wpdb->term_taxonomy AS tt WHERE tt.taxonomy = %s AND tt.term_taxonomy_id IN ($in_delete_tt_ids)", $taxonomy ) );
			$delete_term_ids  = array_map( 'intval', $delete_term_ids );

			$remove = wp_remove_object_terms( $object_id, $delete_term_ids, $taxonomy );
			if ( is_wp_error( $remove ) ) {
				return $remove;
			}
		}
	}

	$t = get_taxonomy( $taxonomy );

	if ( ! $append && isset( $t->sort ) && $t->sort ) {
		$values     = array();
		$term_order = 0;

		$final_tt_ids = wp_get_object_terms(
			$object_id,
			$taxonomy,
			array(
				'fields'                 => 'tt_ids',
				'update_term_meta_cache' => false,
			)
		);

		foreach ( $tt_ids as $tt_id ) {
			if ( in_array( (int) $tt_id, $final_tt_ids, true ) ) {
				$values[] = $wpdb->prepare( '(%d, %d, %d)', $object_id, $tt_id, ++$term_order );
			}
		}

		if ( $values ) {
			if ( false === $wpdb->query( "INSERT INTO $wpdb->term_relationships (object_id, term_taxonomy_id, term_order) VALUES " . implode( ',', $values ) . ' ON DUPLICATE KEY UPDATE term_order = VALUES(term_order)' ) ) {
				return new WP_Error( 'db_insert_error', __( 'Could not insert term relationship into the database.' ), $wpdb->last_error );
			}
		}
	}

	wp_cache_delete( $object_id, $taxonomy . '_relationships' );
	wp_cache_set_terms_last_changed();

	/**
	 * Fires after an object's terms have been set.
	 *
	 * @since 2.8.0
	 *
	 * @param int    $object_id  Object ID.
	 * @param array  $terms      An array of object term IDs or slugs.
	 * @param array  $tt_ids     An array of term taxonomy IDs.
	 * @param string $taxonomy   Taxonomy slug.
	 * @param bool   $append     Whether to append new terms to the old terms.
	 * @param array  $old_tt_ids Old array of term taxonomy IDs.
	 */
	do_action( 'set_object_terms', $object_id, $terms, $tt_ids, $taxonomy, $append, $old_tt_ids );

	return $tt_ids;
}

Hooks

do_action( ‘added_term_relationship’, int $object_id, int $tt_id, string $taxonomy )

Fires immediately after an object-term relationship is added.

do_action( ‘add_term_relationship’, int $object_id, int $tt_id, string $taxonomy )

Fires immediately before an object-term relationship is added.

do_action( ‘set_object_terms’, int $object_id, array $terms, array $tt_ids, string $taxonomy, bool $append, array $old_tt_ids )

Fires after an object’s terms have been set.

Changelog

VersionDescription
2.3.0Introduced.

User Contributed Notes

  1. Skip to note 6 content

    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 new term named after the $terms value and not pick existing term by term_id. This happens because the $terms must be integer or array of integers.

    Wrong:

    $post_id = 15;
    $category_id = '14';
    $taxonomy = 'category';
    wp_set_object_terms( $post_id, $category_id, $taxonomy );

    Correct:

    With the intval() function we cast the second parameter to integer. You can also use (int) $category_id

    $post_id = 15;
    $category_id = 14;
    $taxonomy = 'category';
    wp_set_object_terms( $post_id, intval( $category_id ), $taxonomy );
  2. Skip to note 7 content

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

  3. Skip to note 9 content

    I hope this helps someone when using this function with wp_insert_post() and/or wp_update_post().

    $post_args = [
    'post_title' => $title,
    'post_status' => 'publish',
    'post_type' => $pt,
    'post_content' => $content,
    ];

    $new_post_id = wp_insert_post($post_args);

    wp_set_object_terms($new_post_id->ID === null ? $new_post_id : $new_post_id->ID, array(intval($term_id)), $tax);

    On post creation – $new_post_id exists as an int(id), however, when updating the post, $new_post_id exists as the post object

    To counteract this $new_post_id->ID will fetch the int after post is created, but not before, therefore, using $new_post_id->ID will not work as it doesn’t exist yet

    So set $new_post_id first only if $new_post_id->ID returns null, otherwise use the ID from the object

    This confused me and many many others for ages, so hopefully, this will help someone.

  4. Skip to note 10 content

    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 were 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.
    }

You must log in before being able to contribute a note or feedback.