wp_set_post_categories() – Function | Developer.WordPress.org

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 5 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

wp_set_post_categories( int $post_id, int[]|int $post_categories = array(), bool $append = false ): array|false|WP_Error

In this article