wp-admin/includes/taxonomy.php

   1 <?php
   2 /**
   3  * WordPress Taxonomy Administration API.
   4  *
   5  * @package WordPress
   6  * @subpackage Administration
   7  */
   8
   9 //
  10 // Category
  11 //
  12
  13 /**
  14  * Check whether a category exists.
  15  *
  16  * @since 2.0.0
  17  *
  18  * @see term_exists()
  19  *
  20  * @param int|string $cat_name Category name.
  21  * @param int        $parent   Optional. ID of parent term.
  22  * @return mixed
  23  */
  24 function category_exists( $cat_name, $parent = null ) {
  25         $id = term_exists($cat_name, 'category', $parent);
  26         if ( is_array($id) )
  27                 $id = $id['term_id'];
  28         return $id;
  29 }
  30
  31 /**
  32  * Get category object for given ID and 'edit' filter context.
  33  *
  34  * @since 2.0.0
  35  *
  36  * @param int $id
  37  * @return object
  38  */
  39 function get_category_to_edit( $id ) {
  40         $category = get_term( $id, 'category', OBJECT, 'edit' );
  41         _make_cat_compat( $category );
  42         return $category;
  43 }
  44
  45 /**
  46  * Add a new category to the database if it does not already exist.
  47  *
  48  * @since 2.0.0
  49  *
  50  * @param int|string $cat_name
  51  * @param int        $parent
  52  * @return int|WP_Error
  53  */
  54 function wp_create_category( $cat_name, $parent = 0 ) {
  55         if ( $id = category_exists($cat_name, $parent) )
  56                 return $id;
  57
  58         return wp_insert_category( array('cat_name' => $cat_name, 'category_parent' => $parent) );
  59 }
  60
  61 /**
  62  * Create categories for the given post.
  63  *
  64  * @since 2.0.0
  65  *
  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.
  69  */
  70 function wp_create_categories( $categories, $post_id = '' ) {
  71         $cat_ids = array ();
  72         foreach ( $categories as $category ) {
  73                 if ( $id = category_exists( $category ) ) {
  74                         $cat_ids[] = $id;
  75                 } elseif ( $id = wp_create_category( $category ) ) {
  76                         $cat_ids[] = $id;
  77                 }
  78         }
  79
  80         if ( $post_id )
  81                 wp_set_post_categories($post_id, $cat_ids);
  82
  83         return $cat_ids;
  84 }
  85
  86 /**
  87  * Updates an existing Category or creates a new Category.
  88  *
  89  * @since 2.0.0
  90  * @since 2.5.0 $wp_error parameter was added.
  91  * @since 3.0.0 The 'taxonomy' argument was added.
  92  *
  93  * @param array $catarr {
  94  *     Array of arguments for inserting a new category.
  95  *
  96  *     @type int        $cat_ID               Categoriy ID. A non-zero value updates an existing category.
  97  *                                            Default 0.
  98  *     @type string     $taxonomy             Taxonomy slug. Defualt 'category'.
  99  *     @type string     $cat_nam              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.
 103  * }
 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.
 107  */
 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 );
 111
 112         if ( trim( $catarr['cat_name'] ) == '' ) {
 113                 if ( ! $wp_error ) {
 114                         return 0;
 115                 } else {
 116                         return new WP_Error( 'cat_name', __( 'You did not enter a category name.' ) );
 117                 }
 118         }
 119
 120         $catarr['cat_ID'] = (int) $catarr['cat_ID'];
 121
 122         // Are we updating or creating?
 123         $update = ! empty ( $catarr['cat_ID'] );
 124
 125         $name = $catarr['cat_name'];
 126         $description = $catarr['category_description'];
 127         $slug = $catarr['category_nicename'];
 128         $parent = (int) $catarr['category_parent'];
 129         if ( $parent < 0 ) {
 130                 $parent = 0;
 131         }
 132
 133         if ( empty( $parent )
 134                 || ! term_exists( $parent, $catarr['taxonomy'] )
 135                 || ( $catarr['cat_ID'] && term_is_ancestor_of( $catarr['cat_ID'], $parent, $catarr['taxonomy'] ) ) ) {
 136                 $parent = 0;
 137         }
 138
 139         $args = compact('name', 'slug', 'parent', 'description');
 140
 141         if ( $update ) {
 142                 $catarr['cat_ID'] = wp_update_term( $catarr['cat_ID'], $catarr['taxonomy'], $args );
 143         } else {
 144                 $catarr['cat_ID'] = wp_insert_term( $catarr['cat_name'], $catarr['taxonomy'], $args );
 145         }
 146
 147         if ( is_wp_error( $catarr['cat_ID'] ) ) {
 148                 if ( $wp_error ) {
 149                         return $catarr['cat_ID'];
 150                 } else {
 151                         return 0;
 152                 }
 153         }
 154         return $catarr['cat_ID']['term_id'];
 155 }
 156
 157 /**
 158  * Aliases wp_insert_category() with minimal args.
 159  *
 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.
 162  *
 163  * @since 2.0.0
 164  *
 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.
 167  */
 168 function wp_update_category($catarr) {
 169         $cat_ID = (int) $catarr['cat_ID'];
 170
 171         if ( isset($catarr['category_parent']) && ($cat_ID == $catarr['category_parent']) )
 172                 return false;
 173
 174         // First, get all of the original fields
 175         $category = get_term( $cat_ID, 'category', ARRAY_A );
 176         _make_cat_compat( $category );
 177
 178         // Escape data pulled from DB.
 179         $category = wp_slash($category);
 180
 181         // Merge old and new fields with new fields overwriting old ones.
 182         $catarr = array_merge($category, $catarr);
 183
 184         return wp_insert_category($catarr);
 185 }
 186
 187 //
 188 // Tags
 189 //
 190
 191 /**
 192  * Check whether a post tag with a given name exists.
 193  *
 194  * @since 2.3.0
 195  *
 196  * @param int|string $tag_name
 197  * @return mixed
 198  */
 199 function tag_exists($tag_name) {
 200         return term_exists($tag_name, 'post_tag');
 201 }
 202
 203 /**
 204  * Add a new tag to the database if it does not already exist.
 205  *
 206  * @since 2.3.0
 207  *
 208  * @param int|string $tag_name
 209  * @return array|WP_Error
 210  */
 211 function wp_create_tag($tag_name) {
 212         return wp_create_term( $tag_name, 'post_tag');
 213 }
 214
 215 /**
 216  * Get comma-separated list of tags available to edit.
 217  *
 218  * @since 2.3.0
 219  *
 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
 223  */
 224 function get_tags_to_edit( $post_id, $taxonomy = 'post_tag' ) {
 225         return get_terms_to_edit( $post_id, $taxonomy);
 226 }
 227
 228 /**
 229  * Get comma-separated list of terms available to edit for the given post ID.
 230  *
 231  * @since 2.8.0
 232  *
 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
 236  */
 237 function get_terms_to_edit( $post_id, $taxonomy = 'post_tag' ) {
 238         $post_id = (int) $post_id;
 239         if ( !$post_id )
 240                 return false;
 241
 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' );
 246         }
 247
 248         if ( ! $terms ) {
 249                 return false;
 250         }
 251         if ( is_wp_error( $terms ) ) {
 252                 return $terms;
 253         }
 254         $term_names = array();
 255         foreach ( $terms as $term ) {
 256                 $term_names[] = $term->name;
 257         }
 258
 259         $terms_to_edit = esc_attr( join( ',', $term_names ) );
 260
 261         /**
 262          * Filter the comma-separated list of terms available to edit.
 263          *
 264          * @since 2.8.0
 265          *
 266          * @see get_terms_to_edit()
 267          *
 268          * @param array  $terms_to_edit An array of terms.
 269          * @param string $taxonomy     The taxonomy for which to retrieve terms. Default 'post_tag'.
 270          */
 271         $terms_to_edit = apply_filters( 'terms_to_edit', $terms_to_edit, $taxonomy );
 272
 273         return $terms_to_edit;
 274 }
 275
 276 /**
 277  * Add a new term to the database if it does not already exist.
 278  *
 279  * @since 2.8.0
 280  *
 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
 284  */
 285 function wp_create_term($tag_name, $taxonomy = 'post_tag') {
 286         if ( $id = term_exists($tag_name, $taxonomy) )
 287                 return $id;
 288
 289         return wp_insert_term($tag_name, $taxonomy);
 290 }