wp_set_post_categories( int $post_ID, array|int $post_categories = array(), bool $append = false )

Set categories for a post.


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



(int) (Optional) The Post ID. Does not default to the ID of the global $post. Default 0.


(array|int) (Optional) List of category IDs, or the ID of a single category.

Default value: array()


(bool) (Optional) If true, don't delete existing categories, just add on. If false, replace the categories with the new categories.

Default value: false


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


File: wp-includes/post.php

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


Version Description
2.1.0 Introduced.

© 2003–2019 WordPress Foundation
Licensed under the GNU GPLv2+ License.