wp_insert_category()
云策文档标注
概述
wp_insert_category() 函数用于更新现有分类或创建新分类，是 WordPress 分类管理的核心函数。它接受一个参数数组来定义分类属性，并返回分类 ID 或 WP_Error 对象。
关键要点
- 函数功能：通过 $catarr 参数数组更新或创建分类，$cat_ID 非零时更新，为零时创建。
- 参数说明：$catarr 包含 cat_ID、taxonomy、cat_name、category_description、category_nicename、category_parent 等键，其中 category_nicename 设置 slug。
- 返回值：成功时返回新分类或更新分类的 ID，失败时根据 $wp_error 参数返回 0 或 WP_Error。
- 相关函数：wp_create_category() 是简化版本，wp_update_category() 是其别名。
代码示例
//Define the category
$wpdocs_cat = array('cat_name' => 'Wpdocs Category', 'category_description' => 'A Cool Category', 'category_nicename' => 'category-slug', 'category_parent' => '');
// Create the category
$wpdocs_cat_id = wp_insert_category($wpdocs_cat);注意事项
- cat_name 必须非空，否则函数可能返回 0 或 WP_Error。
- category_nicename 用于设置 URL 友好的 slug，而非显示名称。
- taxonomy 参数默认为 'category'，从 WordPress 3.0.0 开始支持。
原文内容
Updates an existing Category or creates a new Category.
Parameters
$catarrarrayrequired-
Array of arguments for inserting a new category.
cat_IDintCategory ID. A non-zero value updates an existing category.
Default 0.taxonomystringTaxonomy slug. Default'category'.cat_namestringCategory name. Default empty.category_descriptionstringCategory description. Default empty.category_nicenamestringCategory nice (display) name. Default empty.category_parentint|stringCategory parent ID. Default empty.
$wp_errorbooloptional-
Default:
false
Source
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'];
}
Skip to note 2 content
Codex
To insert a new category:
//Define the category $wpdocs_cat = array('cat_name' => 'Wpdocs Category', 'category_description' => 'A Cool Category', 'category_nicename' => 'category-slug', 'category_parent' => ''); // Create the category $wpdocs_cat_id = wp_insert_category($wpdocs_cat);