wp_set_post_categories()

💡 云策文档标注

概述

wp_set_post_categories() 函数用于为文章设置分类。它接受文章ID、分类ID数组和追加标志作为参数，并返回受影响分类的术语分类ID数组或错误信息。

关键要点

函数参数包括 $post_id（文章ID，默认0）、$post_categories（分类ID数组或单个ID，默认空数组）和 $append（追加标志，默认false）。
如果未提供分类且文章类型为 'post'，将使用默认分类；可通过 default_category_post_types 过滤器扩展此行为。
当 $append 为 false 时，函数会覆盖现有分类；为 true 时则追加新分类。
函数内部调用 wp_set_post_terms() 实现功能，适用于标准分类设置。
相关函数包括 wp_set_object_terms()（提供更细粒度控制）和 wp_set_post_terms()。

代码示例

// 替换文章分类为ID 1的分类
wp_set_post_categories( $post_id, array( 1 ) );

// 追加分类ID 2到现有分类
wp_set_post_categories( $post_id, array( 2 ), true );

注意事项

注意：如果传递无效的分类ID，它将在更新前被移除，且不会包含在返回数组中。
对于自定义分类法或更复杂的场景，建议使用 wp_set_object_terms()。

📄 原文内容

Sets categories for a post.

Description

If no categories are provided, the default category is used.

Parameters

$post_idintoptional: The Post ID. Does not default to the ID of the global $post. Default 0.
$post_categoriesint[]|intoptional: List of category IDs, or the ID of a single category.

Default:array()
$appendbooloptional: If true, don’t delete existing categories, just add on.
If false, replace the categories with the new categories.

Default:false

Return

array|false|WP_Error Array of term taxonomy IDs of affected categories. WP_Error or false on failure.

More Information

If no categories are passed with a post ID that has a post type of post, the default category will be used.

Be careful, as wp_set_post_categories will overwrite any existing categories already assigned to the post unless $append is set to true.

If an ID is passed with the categories array that is not associated with a valid category, it will be stripped before the object terms are updated and from the return array.

wp_set_object_terms() performs the same function with more granular control for built in categories and can also be used to set any custom taxonomies.

Source

function wp_set_post_categories( $post_id = 0, $post_categories = array(), $append = false ) {
	$post_id     = (int) $post_id;
	$post_type   = get_post_type( $post_id );
	$post_status = get_post_status( $post_id );

	// If $post_categories isn't already an array, make it one.
	$post_categories = (array) $post_categories;

	if ( empty( $post_categories ) ) {
		/**
		 * Filters post types (in addition to 'post') that require a default category.
		 *
		 * @since 5.5.0
		 *
		 * @param string[] $post_types An array of post type names. Default empty array.
		 */
		$default_category_post_types = apply_filters( 'default_category_post_types', array() );

		// Regular posts always require a default category.
		$default_category_post_types = array_merge( $default_category_post_types, array( 'post' ) );

		if ( in_array( $post_type, $default_category_post_types, true )
			&& is_object_in_taxonomy( $post_type, 'category' )
			&& 'auto-draft' !== $post_status
		) {
			$post_categories = array( get_option( 'default_category' ) );
			$append          = false;
		} else {
			$post_categories = array();
		}
	} elseif ( 1 === count( $post_categories ) && '' === reset( $post_categories ) ) {
		return true;
	}

	return wp_set_post_terms( $post_id, $post_categories, 'category', $append );
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘default_category_post_types’, string[] $post_types ): Filters post types (in addition to ‘post’) that require a default category.

Uses	Description
is_object_in_taxonomy()`wp-includes/taxonomy.php`	Determines if the given object type is associated with the given taxonomy.
wp_set_post_terms()`wp-includes/post.php`	Sets the terms for a post.
get_post_type()`wp-includes/post.php`	Retrieves the post type of the current post or of a given post.
get_post_status()`wp-includes/post.php`	Retrieves the post status based on the post ID.
apply_filters()`wp-includes/plugin.php`	Calls the callback functions that have been added to a filter hook.
get_option()`wp-includes/option.php`	Retrieves an option value based on an option name.

Show 2 more Show less

Used by	Description
wp_create_categories()`wp-admin/includes/taxonomy.php`	Creates categories for the given post.
wp_set_post_cats()`wp-includes/deprecated.php`	Sets the categories that the post ID belongs to.
wp_insert_post()`wp-includes/post.php`	Inserts or update a post.
wp_xmlrpc_server::mt_setPostCategories()`wp-includes/class-wp-xmlrpc-server.php`	Sets categories for a post.

Changelog

Version	Description
2.1.0	Introduced.

User Contributed Notes

Skip to note 2 content

Nikola Papratovic

7 years ago

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
If you want to move post from one category to another programmatically:

Note that if we don’t set the third parameter, by default it is false, meaning you won’t append categories, you will replace them:
```
 wp_set_post_categories( $post_id, array( 1 ) ); 
```
Log in to add feedback

云策 WordPress 开发者社区

函数文档