云策 WordPress 开发者社区

函数文档

wp_set_object_terms()

查看官方原文 ↗
💡 云策文档标注

概述

wp_set_object_terms() 函数用于建立对象（如文章、链接）与分类法术语之间的关系，可创建不存在的术语或关系。它接受对象ID、术语、分类法和追加标志作为参数，返回受影响的术语分类法ID数组或WP_Error。

关键要点

  • 核心功能：关联对象与分类法术语，自动创建不存在的术语（基于slug）和关系。
  • 参数说明：$object_id（整数，必需）为对象ID；$terms（字符串、整数或数组，必需）可以是术语slug、ID或其数组，空数组会移除所有相关术语；$taxonomy（字符串，必需）指定分类法；$append（布尔值，可选，默认false）控制是否追加术语（false时删除差异）。
  • 返回值：成功时返回术语分类法ID数组（注意是term_taxonomy_ids而非term_ids），失败返回WP_Error；空$terms返回空数组表示成功移除。
  • 注意事项：函数不检查对象与分类法之间的关联性，可能配对不相关的术语；$terms参数中整数被解释为术语ID，字符串可能被误认为slug导致创建新术语；建议使用wp_set_post_terms()进行更严格的验证。
  • 相关钩子：包括add_term_relationship、added_term_relationship和set_object_terms，用于在关系添加前后触发动作。

代码示例

// 设置文章分类（替换现有分类）
$post_id = 42;
$category_ids = array(14, 15);
$taxonomy = 'category';
wp_set_object_terms($post_id, $category_ids, $taxonomy);

// 追加分类而不移除现有分类
wp_set_object_terms($post_id, array(16), $taxonomy, true);

// 移除所有分类
wp_set_object_terms($post_id, array(), $taxonomy);

注意事项

  • 确保$terms参数为整数或整数数组以避免意外创建新术语；字符串值可能被解释为slug导致新术语创建。
  • 函数返回的是term_taxonomy_ids，而非term_ids，这可能在数据处理时造成混淆。
  • 使用wp_set_post_terms()作为替代，它提供了更好的值检查和验证，特别是在处理分类法和层次术语时。
📄 原文内容

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();
	$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;
		}

		$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;
}

View all references View on Trac View on GitHub

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.

Uses Description
wp_cache_set_terms_last_changed()wp-includes/taxonomy.php

Sets the last changed time for the ‘terms’ cache group.
wp_cache_delete()wp-includes/cache.php

Removes the cache contents matching key and group.
wp_update_term_count()wp-includes/taxonomy.php

Updates the amount of terms in taxonomy.
wp_get_object_terms()wp-includes/taxonomy.php

Retrieves the terms associated with the given object(s), in the supplied taxonomies.
wp_insert_term()wp-includes/taxonomy.php

Adds a new term to the database.
wp_remove_object_terms()wp-includes/taxonomy.php

Removes term(s) associated with a given object.
term_exists()wp-includes/taxonomy.php

Determines whether a taxonomy term exists.
taxonomy_exists()wp-includes/taxonomy.php

Determines whether the taxonomy name exists.
wpdb::insert()wp-includes/class-wpdb.php

Inserts a row into the table.
wpdb::get_col()wp-includes/class-wpdb.php

Retrieves one column from the database.
wpdb::query()wp-includes/class-wpdb.php

Performs a database query, using current database connection.
__()wp-includes/l10n.php

Retrieves the translation of $text.
get_taxonomy()wp-includes/taxonomy.php

Retrieves the taxonomy object of $taxonomy.
do_action()wp-includes/plugin.php

Calls the callback functions that have been added to an action hook.
wpdb::get_var()wp-includes/class-wpdb.php

Retrieves one value from the database.
wpdb::prepare()wp-includes/class-wpdb.php

Prepares a SQL query for safe execution.
is_wp_error()wp-includes/load.php

Checks whether the given variable is a WordPress Error.
WP_Error::__construct()wp-includes/class-wp-error.php

Initializes the error.

Show 13 moreShow less

Used by Description
WP_REST_Posts_Controller::handle_terms()wp-includes/rest-api/endpoints/class-wp-rest-posts-controller.php

Updates the post’s terms from a REST request.
media_upload_form_handler()wp-admin/includes/media.php

Handles form submissions for the legacy media uploader.
wp_ajax_save_attachment_compat()wp-admin/includes/ajax-actions.php

Handles saving backward compatible attachment attributes via AJAX.
wp_set_link_cats()wp-admin/includes/bookmark.php

Updates link with the specified link categories.
wp_add_object_terms()wp-includes/taxonomy.php

Adds term(s) associated with a given object.
wp_delete_term()wp-includes/taxonomy.php

Removes a term from the database.
wp_set_post_terms()wp-includes/post.php

Sets the terms for a post.
wp_update_nav_menu_item()wp-includes/nav-menu.php

Saves the properties of a menu item or create a new one.

Show 3 moreShow less

Changelog

Version Description
2.3.0 Introduced.

User Contributed Notes

  1. Skip to note 6 content


    Darko G.


    You must log in to vote on the helpfulness of this noteVote results for this note: 6You must log in to vote on the helpfulness of this note

    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


    Codex


    You must log in to vote on the helpfulness of this noteVote results for this note: 3You must log in to vote on the helpfulness of this note

    Setting a Post’s Categories

    If you want to set the categories of a post with the ID of 42:

    </pre>
<p>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.</p>
				</div><!-- .comment-content -->

					<section id='feedback-1120' class='wporg-has-embedded-code feedback hide-if-js' data-comment-count='0'>
</section><!-- .feedback -->
<footer class='feedback-links wporg-dot-link-list' >
<a role="button" class="feedback-login" href="https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_set_object_terms%2F%3Freplytocom%3D1120%23feedback-editor-1120" rel="nofollow">Log in to add feedback</a></footer>
</article><!-- .comment-body -->
</li>
			<li id="comment-1122" data-comment-id="1122" class="comment byuser comment-author-codex odd alt thread-odd thread-alt depth-1">
			<article id="div-comment-1122" class="comment-body">

							<a href="#comment-content-1122" class="screen-reader-text">Skip to note 8 content</a>
				<header class="comment-meta">
					<div class="comment-author vcard">
						<span class="comment-author-attribution">
						<a href="https://profiles.wordpress.org/codex/" rel="external nofollow" class="url">Codex</a>						</span>
						<a class="comment-date" href="https://developer.wordpress.org/reference/functions/wp_set_object_terms/#comment-1122">
							<time datetime="2016-02-12T17:29:39+00:00">
							10 years ago							</time>
						</a>

																													</div>
					<div class="user-note-voting" data-nonce="ea85424f60" data-can-vote="false"><a class="user-note-voting-up" title="You must log in to vote on the helpfulness of this note" data-id="1122" data-vote="up" href="https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_set_object_terms%2F%23comment-1122"><span class="screen-reader-text">You must log in to vote on the helpfulness of this note</span></a><span class="user-note-voting-count " title="80% like this"><span class="screen-reader-text">Vote results for this note: </span>3</span><a class="user-note-voting-down" title="You must log in to vote on the helpfulness of this note" data-id="1122" data-vote="down" href="https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_set_object_terms%2F%23comment-1122"><span class="screen-reader-text">You must log in to vote on the helpfulness of this note</span></a></div>				</header>
				<!-- .comment-metadata -->
			
				<div class="wporg-has-embedded-code comment-content" id="comment-content-1122">
				<p><strong>Removing All Categories From a Post</strong></p>
<p>If you want to clear/remove all categories from a post, you can pass an empty value for $terms:</p>
<pre class="wp-block-code"><code lang="php" class="language-php ">

  3. Skip to note 9 content


    zenith


    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note

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

    $post_args = [<br />
    'post_title' => $title,<br />
    'post_status' => 'publish',<br />
    'post_type' => $pt,<br />
    'post_content' => $content,<br />
    ];</p>
    <p>$new_post_id = wp_insert_post($post_args);</p>
    <p>wp_set_object_terms($new_post_id->ID === null ? $new_post_id : $new_post_id->ID, array(intval($term_id)), $tax);<br />

    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.