Question

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

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

---

参数

$object_id

(int) (Required) The object to relate to.

$terms

(string|int|array) (Required) A single term slug, single term id, or array of either term slugs or ids. Will replace all existing 相关函数 terms in this taxonomy. Passing an empty value will remove all 相关函数 terms.

$taxonomy

(string) (Required) The context in which to relate the term to the object.

$append

(bool) (Optional) If false will delete difference of terms.

Default value: false

---

返回值

(array|WP_Error) Term taxonomy IDs of the affected terms.

---

源代码

File: wp-includes/taxonomy.php

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 ( !is_array($terms) )
		$terms = array($terms);

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

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

	foreach ( (array) $terms as $term) {
		if ( !strlen(trim($term)) )
			continue;

		if ( !$term_info = term_exists($term, $taxonomy) ) {
			// 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'));
		foreach ( $tt_ids as $tt_id )
			if ( in_array($tt_id, $final_tt_ids) )
				$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 " . join( ',', $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_delete( 'last_changed', 'terms' );

	/**
	 * 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 terms.
	 * @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;
}

---

更新日志

Version	description
2.3.0	Introduced.

---

相关函数

Uses

• wp-includes/cache.php: wp_cache_delete()
• wp-includes/l10n.php: __()
• wp-includes/taxonomy.php: wp_update_term_count()
• wp-includes/taxonomy.php: wp_get_object_terms()
• wp-includes/taxonomy.php: wp_insert_term()
• wp-includes/taxonomy.php: wp_remove_object_terms()
• wp-includes/taxonomy.php: add_term_relationship
• wp-includes/taxonomy.php: added_term_relationship
• wp-includes/taxonomy.php: set_object_terms
• wp-includes/taxonomy.php: term_exists()
• wp-includes/taxonomy.php: taxonomy_exists()
• wp-includes/taxonomy.php: get_taxonomy()
• wp-includes/plugin.php: do_action()
• wp-includes/wp-db.php: wpdb::get_var()
• wp-includes/wp-db.php: wpdb::insert()
• wp-includes/wp-db.php: wpdb::get_col()
• wp-includes/wp-db.php: wpdb::query()
• wp-includes/wp-db.php: wpdb::prepare()
• wp-includes/load.php: is_wp_error()
• wp-includes/class-wp-error.php: WP_Error::__construct()
Show 15 more uses Hide more uses

---

Used By

• wp-includes/rest-api/endpoints/class-wp-rest-posts-controller.php: WP_REST_Posts_Controller::handle_terms()
• wp-admin/includes/media.php: media_upload_form_handler()
• wp-admin/includes/ajax-actions.php: wp_ajax_save_attachment_compat()
• wp-admin/includes/bookmark.php: wp_set_link_cats()
• wp-includes/taxonomy.php: wp_add_object_terms()
• wp-includes/taxonomy.php: wp_delete_term()
• wp-includes/post.php: wp_set_post_terms()
• wp-includes/nav-menu.php: wp_update_nav_menu_item()
Show 3 more used by Hide more used by

---

User Contributed Notes

1. Skip to note content 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 Contributed by Codex

   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 源代码, 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.

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 源代码, 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.
}

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' ); ?>