Set terms for a post.
This function will only work on the native post type. For a taxonomy on a custom post type use wp_set_object_terms().
Uses wp_set_object_terms().

wp_set_post_terms() 描述


<?php wp_set_post_terms$post_id$terms$taxonomy$append ?>

wp_set_post_terms() 用法



(integer) (必填) Post ID.

默认值: 0


(string,array) (可选) List of terms. Can be an array or a comma separated string. If you want to enter terms of a hierarchical taxonomy like categories, then use IDs. If you want to add non-hierarchical terms like tags, then use names.

默认值: array


(string) (可选) Possible values for example: 'category', 'post_tag', 'taxonomy slug'

默认值: post_tag


(boolean) (可选) If true, tags will be appended to the post. If false, tags will replace existing tags.

默认值: false

wp_set_post_terms() 参数



  • (array) An array of the terms affected if successful,
  • (boolean) false if integer value of $post_id evaluates as false (if ( ! (int) $post_id )),
  • (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).

wp_set_post_terms() 返回值


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:

/* ----------------------------------
 * wordpress之魂 © http://wphun.com
 * ---------------------------------- */
$term_id = term_exists( $term, $taxonomy, $parent );

You may also need to pass by reference:

/* ----------------------------------
 * wordpress之魂 © http://wphun.com
 * ---------------------------------- */
wp_set_post_terms( $post_id, $term, &$taxonomy );

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.

/* ----------------------------------
 * wordpress之魂 © http://wphun.com
 * ---------------------------------- */

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

wp_set_post_terms() 注意


添加于 版本: 2.8.0

wp_set_post_terms() 历史


wp_set_post_terms() 函数的代码位于 wp-includes/post.php.

/* ----------------------------------
 * wordpress之魂 © http://wphun.com
 * ---------------------------------- */
 * Set the terms for a post.
 * @since 2.8.0
 * @see wp_set_object_terms()
 * @param int    $post_id  Optional. The Post ID. Does not default to the ID of the global $post.
 * @param string $tags     Optional. The tags to set for the post, separated by commas. Default empty.
 * @param string $taxonomy Optional. Taxonomy name. Default 'post_tag'.
 * @param bool   $append   Optional. If true, don't delete existing tags, just add on. If false,
 *                         replace the tags with the new tags. Default false.
 * @return array|false|WP_Error Array of affected term IDs. WP_Error or false on failure.
function wp_set_post_terms( $post_id = 0, $tags = '', $taxonomy = 'post_tag', $append = false ) {
	$post_id = (int) $post_id;

	if ( !$post_id )
		return false;

	if ( empty($tags) )
		$tags = array();

	if ( ! is_array( $tags ) ) {
		$comma = _x( ',', 'tag delimiter' );
		if ( ',' !== $comma )
			$tags = str_replace( $comma, ',', $tags );
		$tags = explode( ',', trim( $tags, " 
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 ) ) {
		$tags = array_unique( array_map( 'intval', $tags ) );

	return wp_set_object_terms( $post_id, $tags, $taxonomy, $append );

wp_set_post_terms() 源文件