wp_set_post_categories() WordPress Function
The wp_set_post_categories() function allows you to set the categories for a post in WordPress. This function will return true if the categories are successfully set, and false if there is an error.
wp_set_post_categories( int $post_ID, int[]|int $post_categories = array(), bool $append = false ) #
Set categories for a post.
Description
If no categories are provided, the default category is used.
Parameters
- $post_ID
(int)(Optional) The Post ID. Does not default to the ID of the global $post. Default 0.
- $post_categories
(int[]|int)(Optional) List of category IDs, or the ID of a single category.
Default value: array()
- $append
(bool)(Optional)If true, don't delete existing categories, just add on. If false, replace the categories with the new categories.
Default value: 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
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 ); }
Expand full source codeCollapse full source codeView on TracView on GitHub
Changelog
Version | Description |
---|---|
2.1.0 | Introduced. |