wp_insert_category() │ WP 2.0.0

Inserts a new category into the database. Or updates an existing category by specifying a category ID.

You can use a simpler function wp_create_category() to add a category. You only need to pass the category name and the ID of the parent category into it.

If error Fatal error: Call to undefined function wp_insert_category() appears, you need to include /wp-admin/includes/taxonomy.php file:

require_once ABSPATH . '/wp-admin/includes/taxonomy.php';

wp_insert_category( $catarr, $wp_error );
Uses: wp_update_term(), wp_insert_term()
Used By: wp_create_category()

No Hooks.

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.

Usage

wp_insert_category( $catarr, $wp_error );
$catarr(array) (required)

Parameters of the new category. Valid parameters:

$cat_defaults = [
  'cat_ID' => 0,                // The ID of the category to be updated. 0 - add new category.
  'cat_name' => '',             // category name. Required.
  'category_description' => '', // category description
  'category_nicename' => '',    // category slag
  'category_parent' => 0,       // ID of the parent category
  'taxonomy' => 'category'      // taxonomy. Change to add a different taxonomy element.
								// For example for labels it will be post_tag
];

It is recommended to specify only necessary parameters.

$wp_error(bool)
true - will return WP_Error object if it fails.
Default: false

Examples

0

#1 Adding a new category

To insert a new category into the site, use this code:

$cat_data = [
	'cat_name' => 'new category',
	'category_description' => 'New category description',
	'category_nicename' => 'new-cat'
];

//insert
$cat_id = wp_insert_category( $cat_data );

if( $cat_id )
	echo 'Category is added';
else
	echo 'Failed to add category';
0

#2 Update an existing category

Let's update an existing category with ID=7. Change it's name:

$updated = wp_insert_category( [
	'cat_ID' => 5,
	'cat_name' => 'New name'
] );

if( $updated ){
	echo "the category with $updated has been updated";
}
-1

#3 Adding a custom taxonomy element

The function allows you to add elements of custom taxonomies, not just categories. Let's add a tag:

$tag_id = wp_insert_category( [
	'cat_name' => 'label',
	'taxonomy' => 'post_tag'
] );

Changelog

Since 2.0.0 Introduced.
Since 2.5.0 $wp_error parameter was added.
Since 3.0.0 The 'taxonomy' argument was added.

wp_insert_category() code WP 6.5.2

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'];
}

wp_insert (insert in DB)

Term (taxonomies terms)

Categories