3 * WordPress Taxonomy Administration API.
6 * @subpackage Administration
14 * Check whether a category exists.
20 * @param int|string $cat_name Category name.
21 * @param int $parent Optional. ID of parent term.
24 function category_exists( $cat_name, $parent = null ) {
25 $id = term_exists($cat_name, 'category', $parent);
32 * Get category object for given ID and 'edit' filter context.
39 function get_category_to_edit( $id ) {
40 $category = get_term( $id, 'category', OBJECT, 'edit' );
41 _make_cat_compat( $category );
46 * Add a new category to the database if it does not already exist.
50 * @param int|string $cat_name
52 * @return int|WP_Error
54 function wp_create_category( $cat_name, $parent = 0 ) {
55 if ( $id = category_exists($cat_name, $parent) )
58 return wp_insert_category( array('cat_name' => $cat_name, 'category_parent' => $parent) );
62 * Create categories for the given post.
66 * @param array $categories List of categories to create.
67 * @param int $post_id Optional. The post ID. Default empty.
68 * @return List of categories to create for the given post.
70 function wp_create_categories( $categories, $post_id = '' ) {
72 foreach ( $categories as $category ) {
73 if ( $id = category_exists( $category ) ) {
75 } elseif ( $id = wp_create_category( $category ) ) {
81 wp_set_post_categories($post_id, $cat_ids);
87 * Updates an existing Category or creates a new Category.
90 * @since 2.5.0 $wp_error parameter was added.
91 * @since 3.0.0 The 'taxonomy' argument was added.
93 * @param array $catarr {
94 * Array of arguments for inserting a new category.
96 * @type int $cat_ID Categoriy ID. A non-zero value updates an existing category.
98 * @type string $taxonomy Taxonomy slug. Defualt 'category'.
99 * @type string $cat_name Category name. Default empty.
100 * @type string $category_description Category description. Default empty.
101 * @type string $category_nicename Category nice (display) name. Default empty.
102 * @type int|string $category_parent Category parent ID. Default empty.
104 * @param bool $wp_error Optional. Default false.
105 * @return int|object The ID number of the new or updated Category on success. Zero or a WP_Error on failure,
106 * depending on param $wp_error.
108 function wp_insert_category( $catarr, $wp_error = false ) {
109 $cat_defaults = array( 'cat_ID' => 0, 'taxonomy' => 'category', 'cat_name' => '', 'category_description' => '', 'category_nicename' => '', 'category_parent' => '' );
110 $catarr = wp_parse_args( $catarr, $cat_defaults );
112 if ( trim( $catarr['cat_name'] ) == '' ) {
116 return new WP_Error( 'cat_name', __( 'You did not enter a category name.' ) );
120 $catarr['cat_ID'] = (int) $catarr['cat_ID'];
122 // Are we updating or creating?
123 $update = ! empty ( $catarr['cat_ID'] );
125 $name = $catarr['cat_name'];
126 $description = $catarr['category_description'];
127 $slug = $catarr['category_nicename'];
128 $parent = (int) $catarr['category_parent'];
133 if ( empty( $parent )
134 || ! term_exists( $parent, $catarr['taxonomy'] )
135 || ( $catarr['cat_ID'] && term_is_ancestor_of( $catarr['cat_ID'], $parent, $catarr['taxonomy'] ) ) ) {
139 $args = compact('name', 'slug', 'parent', 'description');
142 $catarr['cat_ID'] = wp_update_term( $catarr['cat_ID'], $catarr['taxonomy'], $args );
144 $catarr['cat_ID'] = wp_insert_term( $catarr['cat_name'], $catarr['taxonomy'], $args );
147 if ( is_wp_error( $catarr['cat_ID'] ) ) {
149 return $catarr['cat_ID'];
154 return $catarr['cat_ID']['term_id'];
158 * Aliases wp_insert_category() with minimal args.
160 * If you want to update only some fields of an existing category, call this
161 * function with only the new values set inside $catarr.
165 * @param array $catarr The 'cat_ID' value is required. All other keys are optional.
166 * @return int|bool The ID number of the new or updated Category on success. Zero or FALSE on failure.
168 function wp_update_category($catarr) {
169 $cat_ID = (int) $catarr['cat_ID'];
171 if ( isset($catarr['category_parent']) && ($cat_ID == $catarr['category_parent']) )
174 // First, get all of the original fields
175 $category = get_term( $cat_ID, 'category', ARRAY_A );
176 _make_cat_compat( $category );
178 // Escape data pulled from DB.
179 $category = wp_slash($category);
181 // Merge old and new fields with new fields overwriting old ones.
182 $catarr = array_merge($category, $catarr);
184 return wp_insert_category($catarr);
192 * Check whether a post tag with a given name exists.
196 * @param int|string $tag_name
199 function tag_exists($tag_name) {
200 return term_exists($tag_name, 'post_tag');
204 * Add a new tag to the database if it does not already exist.
208 * @param int|string $tag_name
209 * @return array|WP_Error
211 function wp_create_tag($tag_name) {
212 return wp_create_term( $tag_name, 'post_tag');
216 * Get comma-separated list of tags available to edit.
220 * @param int $post_id
221 * @param string $taxonomy Optional. The taxonomy for which to retrieve terms. Default 'post_tag'.
222 * @return string|bool|WP_Error
224 function get_tags_to_edit( $post_id, $taxonomy = 'post_tag' ) {
225 return get_terms_to_edit( $post_id, $taxonomy);
229 * Get comma-separated list of terms available to edit for the given post ID.
233 * @param int $post_id
234 * @param string $taxonomy Optional. The taxonomy for which to retrieve terms. Default 'post_tag'.
235 * @return string|bool|WP_Error
237 function get_terms_to_edit( $post_id, $taxonomy = 'post_tag' ) {
238 $post_id = (int) $post_id;
242 $terms = get_object_term_cache( $post_id, $taxonomy );
243 if ( false === $terms ) {
244 $terms = wp_get_object_terms( $post_id, $taxonomy );
245 wp_cache_add( $post_id, $terms, $taxonomy . '_relationships' );
251 if ( is_wp_error( $terms ) ) {
254 $term_names = array();
255 foreach ( $terms as $term ) {
256 $term_names[] = $term->name;
259 $terms_to_edit = esc_attr( join( ',', $term_names ) );
262 * Filter the comma-separated list of terms available to edit.
266 * @see get_terms_to_edit()
268 * @param array $terms_to_edit An array of terms.
269 * @param string $taxonomy The taxonomy for which to retrieve terms. Default 'post_tag'.
271 $terms_to_edit = apply_filters( 'terms_to_edit', $terms_to_edit, $taxonomy );
273 return $terms_to_edit;
277 * Add a new term to the database if it does not already exist.
281 * @param int|string $tag_name
282 * @param string $taxonomy Optional. The taxonomy for which to retrieve terms. Default 'post_tag'.
283 * @return array|WP_Error
285 function wp_create_term($tag_name, $taxonomy = 'post_tag') {
286 if ( $id = term_exists($tag_name, $taxonomy) )
289 return wp_insert_term($tag_name, $taxonomy);