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.

$wp_error

(bool)(Optional)

Default value: false


Top ↑

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.


Top ↑

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


Top ↑

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


Top ↑

Changelog

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

The content displayed on this page has been created in part by processing WordPress source code files which are made available under the GPLv2 (or a later version) license by the Free Software Foundation. In addition to this, the content includes user-written examples and information. All material is subject to review and curation by the WPPaste.com community.