wp_insert_category

Updates an existing Category or creates a new Category.

Description

(int|object) wp_insert_category( (array) $catarr, (bool) $wp_error = false ); 

Returns (int|object)

The ID number of the new or updated Category on success. Zero or a WP_Error on failure, depending on param $wp_error.

Parameters (2)

0. $catarr (array)
Array of arguments for inserting a new category.

Options

  • cat_ID (int) => 0

    Category ID. A non-zero value updates an existing category.

  • taxonomy (string) => 'category'

    Taxonomy slug.

  • cat_name (string) => ''

    Category name.

  • category_description (string) => ''

    Category description.

  • category_nicename (string) => ''

    Category nice (display) name.

array(

    /**
     * Category ID. A non-zero value updates an existing category.
     *
     * @type int
     */
    'cat_ID' => 0,

    /**
     * Taxonomy slug.
     *
     * @type string
     * @default 'category'
     */
    'taxonomy' => 'category',

    /**
     * Category name.
     *
     * @type string
     * @default ''
     */
    'cat_name' => '',

    /**
     * Category description.
     *
     * @type string
     * @default ''
     */
    'category_description' => '',

    /**
     * Category nice (display) name.
     *
     * @type string
     * @default ''
     */
    'category_nicename' => ''
);        

1. $wp_error — Optional. (bool) => false
Default false.

Usage

  1. if ( !function_exists( 'wp_insert_category' ) ) { 
  2. require_once ABSPATH . '/wp-admin/includes/taxonomy.php'; 
  3.  
  4. // Array of arguments for inserting a new category. 
  5. $catarr = array( 
  6. 'cat_ID' => 0, 
  7. 'taxonomy' => 'category', 
  8. 'cat_name' => '', 
  9. 'category_description' => '', 
  10. 'category_nicename' => '' 
  11. ); 
  12.  
  13. // Optional. Default false. 
  14. $wp_error = false; 
  15.  
  16. // NOTICE! Understand what this does before running. 
  17. $result = wp_insert_category($catarr, $wp_error); 
  18.  

Defined (1)

The function is defined in the following location(s).

/wp-admin/includes/taxonomy.php  
  1. function wp_insert_category( $catarr, $wp_error = false ) { 
  2. $cat_defaults = array( 'cat_ID' => 0, 'taxonomy' => 'category', 'cat_name' => '', 'category_description' => '', 'category_nicename' => '', 'category_parent' => '' ); 
  3. $catarr = wp_parse_args( $catarr, $cat_defaults ); 
  4.  
  5. if ( trim( $catarr['cat_name'] ) == '' ) { 
  6. if ( ! $wp_error ) { 
  7. return 0; 
  8. } else { 
  9. return new WP_Error( 'cat_name', __( 'You did not enter a category name.' ) ); 
  10.  
  11. $catarr['cat_ID'] = (int) $catarr['cat_ID']; 
  12.  
  13. // Are we updating or creating? 
  14. $update = ! empty ( $catarr['cat_ID'] ); 
  15.  
  16. $name = $catarr['cat_name']; 
  17. $description = $catarr['category_description']; 
  18. $slug = $catarr['category_nicename']; 
  19. $parent = (int) $catarr['category_parent']; 
  20. if ( $parent < 0 ) { 
  21. $parent = 0; 
  22.  
  23. if ( empty( $parent ) 
  24. || ! term_exists( $parent, $catarr['taxonomy'] ) 
  25. || ( $catarr['cat_ID'] && term_is_ancestor_of( $catarr['cat_ID'], $parent, $catarr['taxonomy'] ) ) ) { 
  26. $parent = 0; 
  27.  
  28. $args = compact('name', 'slug', 'parent', 'description'); 
  29.  
  30. if ( $update ) { 
  31. $catarr['cat_ID'] = wp_update_term( $catarr['cat_ID'], $catarr['taxonomy'], $args ); 
  32. } else { 
  33. $catarr['cat_ID'] = wp_insert_term( $catarr['cat_name'], $catarr['taxonomy'], $args ); 
  34.  
  35. if ( is_wp_error( $catarr['cat_ID'] ) ) { 
  36. if ( $wp_error ) { 
  37. return $catarr['cat_ID']; 
  38. } else { 
  39. return 0; 
  40. return $catarr['cat_ID']['term_id'];