wp_set_post_categories( int $post_id, int[]|int $post_categories = array(), bool $append = false ): array|false|WP_Error
Sets categories for a post.
Contents
Description
If no categories are provided, the default category is used.
Parameters
-
$post_idint Optional -
The Post ID. Does not default to the ID of the global $post. Default 0.
-
$post_categoriesint[]|int Optional -
List of category IDs, or the ID of a single category.
Default:
array() -
$appendbool Optional -
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
File: wp-includes/post.php.
View all references
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 );
}
Hooks
-
apply_filters( 'default_category_post_types',
string[] $post_types ) -
Filters post types (in addition to ‘post’) that require a default category.
Changelog
| Version | Description |
|---|---|
| 2.1.0 | Introduced. |
User Contributed Notes
You must log in before being able to contribute a note or feedback.
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: