wp_insert_category() WordPress Function
The wp_insert_category() function allows you to insert a new category into your WordPress site. This function takes two arguments: the first is the name of the category, and the second is an array of optional arguments. The optional arguments allow you to set the slug, parent, and description for the new category. If you do not set these arguments, WordPress will generate them for you.
wp_insert_category( array $catarr, bool $wp_error = false ) #
Updates an existing Category or creates a new Category.
Parameters
- $catarr
(array)(Required)Array of arguments for inserting a new category.
- 'cat_ID'
(int) Category ID. A non-zero value updates an existing category. Default 0. - 'taxonomy'
(string) Taxonomy slug. Default 'category'. - 'cat_name'
(string) Category name. Default empty. - 'category_description'
(string) Category description. Default empty. - 'category_nicename'
(string) Category nice (display) name. Default empty. - 'category_parent'
(int|string) Category parent ID. Default empty.
- 'cat_ID'
- $wp_error
(bool)(Optional)
Default value: false
Return
(int|WP_Error) The ID number of the new or updated Category on success. Zero or a WP_Error on failure, depending on param $wp_error
.
More Information
Not all possible members of the $catarr array are listed here.
The value of category_nicename will set the slug. (In WordPress terminology, a “nice” name is one that is sanitized for use in places like URLs. It is not meant for displaying to humans, as you might assume.)
See wp_create_category() for a simpler version which takes just a string instead of an array
Source
File: wp-admin/includes/taxonomy.php
function wp_insert_category( $catarr, $wp_error = false ) { $cat_defaults = array( 'cat_ID' => 0, 'taxonomy' => 'category', 'cat_name' => '', 'category_description' => '', 'category_nicename' => '', 'category_parent' => '', ); $catarr = wp_parse_args( $catarr, $cat_defaults ); if ( '' === trim( $catarr['cat_name'] ) ) { if ( ! $wp_error ) { return 0; } else { return new WP_Error( 'cat_name', __( 'You did not enter a category name.' ) ); } } $catarr['cat_ID'] = (int) $catarr['cat_ID']; // Are we updating or creating? $update = ! empty( $catarr['cat_ID'] ); $name = $catarr['cat_name']; $description = $catarr['category_description']; $slug = $catarr['category_nicename']; $parent = (int) $catarr['category_parent']; if ( $parent < 0 ) { $parent = 0; } if ( empty( $parent ) || ! term_exists( $parent, $catarr['taxonomy'] ) || ( $catarr['cat_ID'] && term_is_ancestor_of( $catarr['cat_ID'], $parent, $catarr['taxonomy'] ) ) ) { $parent = 0; } $args = compact( 'name', 'slug', 'parent', 'description' ); if ( $update ) { $catarr['cat_ID'] = wp_update_term( $catarr['cat_ID'], $catarr['taxonomy'], $args ); } else { $catarr['cat_ID'] = wp_insert_term( $catarr['cat_name'], $catarr['taxonomy'], $args ); } if ( is_wp_error( $catarr['cat_ID'] ) ) { if ( $wp_error ) { return $catarr['cat_ID']; } else { return 0; } } return $catarr['cat_ID']['term_id']; }
Expand full source codeCollapse full source codeView on TracView on GitHub
Changelog
Version | Description |
---|---|
3.0.0 | The 'taxonomy' argument was added. |
2.5.0 | $wp_error parameter was added. |
2.0.0 | Introduced. |