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  * {@internal Missing Short Description}}
  15  *
  16  * @since 2.0.0
  17  *
  18  * @param int|string $cat_name
  19  * @return int
  20  */
  21 function category_exists($cat_name, $parent = 0) {
  22         $id = term_exists($cat_name, 'category', $parent);
  23         if ( is_array($id) )
  24                 $id = $id['term_id'];
  25         return $id;
  26 }
  27
  28 /**
  29  * {@internal Missing Short Description}}
  30  *
  31  * @since 2.0.0
  32  *
  33  * @param int $id
  34  * @return object
  35  */
  36 function get_category_to_edit( $id ) {
  37         $category = get_term( $id, 'category', OBJECT, 'edit' );
  38         _make_cat_compat( $category );
  39         return $category;
  40 }
  41
  42 /**
  43  * {@internal Missing Short Description}}
  44  *
  45  * @since 2.0.0
  46  *
  47  * @param int|string $cat_name
  48  * @param int        $parent
  49  * @return int|WP_Error
  50  */
  51 function wp_create_category( $cat_name, $parent = 0 ) {
  52         if ( $id = category_exists($cat_name, $parent) )
  53                 return $id;
  54
  55         return wp_insert_category( array('cat_name' => $cat_name, 'category_parent' => $parent) );
  56 }
  57
  58 /**
  59  * Create categories for the given post.
  60  *
  61  * @since 2.0.0
  62  *
  63  * @param array $categories List of categories to create.
  64  * @param int   $post_id    Optional. The post ID. Default empty.
  65  * @return List of categories to create for the given post.
  66  */
  67 function wp_create_categories( $categories, $post_id = '' ) {
  68         $cat_ids = array ();
  69         foreach ($categories as $category) {
  70                 if ($id = category_exists($category))
  71                         $cat_ids[] = $id;
  72                 else
  73                         if ($id = wp_create_category($category))
  74                                 $cat_ids[] = $id;
  75         }
  76
  77         if ( $post_id )
  78                 wp_set_post_categories($post_id, $cat_ids);
  79
  80         return $cat_ids;
  81 }
  82
  83 /**
  84  * Updates an existing Category or creates a new Category.
  85  *
  86  * @since 2.0.0
  87  * @since 2.5.0 $wp_error parameter was added.
  88  * @since 3.0.0 The 'taxonomy' argument was added.
  89  *
  90  * @param array $catarr {
  91  *     Array of arguments for inserting a new category.
  92  *
  93  *     @type int        $cat_ID               Categoriy ID. A non-zero value updates an existing category.
  94  *                                            Default 0.
  95  *     @type string     $taxonomy             Taxonomy slug. Defualt 'category'.
  96  *     @type string     $cat_nam              Category name. Default empty.
  97  *     @type string     $category_description Category description. Default empty.
  98  *     @type string     $category_nicename    Category nice (display) name. Default empty.
  99  *     @type int|string $category_parent      Category parent ID. Default empty.
 100  * }
 101  * @param bool  $wp_error Optional. Default false.
 102  * @return int|object The ID number of the new or updated Category on success. Zero or a WP_Error on failure,
 103  *                    depending on param $wp_error.
 104  */
 105 function wp_insert_category( $catarr, $wp_error = false ) {
 106         $cat_defaults = array( 'cat_ID' => 0, 'taxonomy' => 'category', 'cat_name' => '', 'category_description' => '', 'category_nicename' => '', 'category_parent' => '' );
 107         $catarr = wp_parse_args( $catarr, $cat_defaults );
 108
 109         if ( trim( $catarr['cat_name'] ) == '' ) {
 110                 if ( ! $wp_error ) {
 111                         return 0;
 112                 } else {
 113                         return new WP_Error( 'cat_name', __( 'You did not enter a category name.' ) );
 114                 }
 115         }
 116
 117         $catarr['cat_ID'] = (int) $catarr['cat_ID'];
 118
 119         // Are we updating or creating?
 120         $update = ! empty ( $catarr['cat_ID'] );
 121
 122         $name = $catarr['cat_name'];
 123         $description = $catarr['category_description'];
 124         $slug = $catarr['category_nicename'];
 125         $parent = (int) $catarr['category_parent'];
 126         if ( $parent < 0 ) {
 127                 $parent = 0;
 128         }
 129
 130         if ( empty( $parent )
 131                 || ! term_exists( $parent, $catarr['taxonomy'] )
 132                 || ( $catarr['cat_ID'] && term_is_ancestor_of( $catarr['cat_ID'], $parent, $catarr['taxonomy'] ) ) ) {
 133                 $parent = 0;
 134         }
 135
 136         $args = compact('name', 'slug', 'parent', 'description');
 137
 138         if ( $update ) {
 139                 $catarr['cat_ID'] = wp_update_term( $catarr['cat_ID'], $catarr['taxonomy'], $args );
 140         } else {
 141                 $catarr['cat_ID'] = wp_insert_term( $catarr['cat_name'], $catarr['taxonomy'], $args );
 142         }
 143
 144         if ( is_wp_error( $catarr['cat_ID'] ) ) {
 145                 if ( $wp_error ) {
 146                         return $catarr['cat_ID'];
 147                 } else {
 148                         return 0;
 149                 }
 150         }
 151         return $catarr['cat_ID']['term_id'];
 152 }
 153
 154 /**
 155  * Aliases wp_insert_category() with minimal args.
 156  *
 157  * If you want to update only some fields of an existing category, call this
 158  * function with only the new values set inside $catarr.
 159  *
 160  * @since 2.0.0
 161  *
 162  * @param array $catarr The 'cat_ID' value is required. All other keys are optional.
 163  * @return int|bool The ID number of the new or updated Category on success. Zero or FALSE on failure.
 164  */
 165 function wp_update_category($catarr) {
 166         $cat_ID = (int) $catarr['cat_ID'];
 167
 168         if ( isset($catarr['category_parent']) && ($cat_ID == $catarr['category_parent']) )
 169                 return false;
 170
 171         // First, get all of the original fields
 172         $category = get_term( $cat_ID, 'category', ARRAY_A );
 173         _make_cat_compat( $category );
 174
 175         // Escape data pulled from DB.
 176         $category = wp_slash($category);
 177
 178         // Merge old and new fields with new fields overwriting old ones.
 179         $catarr = array_merge($category, $catarr);
 180
 181         return wp_insert_category($catarr);
 182 }
 183
 184 //
 185 // Tags
 186 //
 187
 188 /**
 189  * {@internal Missing Short Description}}
 190  *
 191  * @since 2.3.0
 192  *
 193  * @param int|string $tag_name
 194  * @return mixed
 195  */
 196 function tag_exists($tag_name) {
 197         return term_exists($tag_name, 'post_tag');
 198 }
 199
 200 /**
 201  * {@internal Missing Short Description}}
 202  *
 203  * @since 2.3.0
 204  *
 205  * @param int|string $tag_name
 206  * @return array|WP_Error
 207  */
 208 function wp_create_tag($tag_name) {
 209         return wp_create_term( $tag_name, 'post_tag');
 210 }
 211
 212 /**
 213  * {@internal Missing Short Description}}
 214  *
 215  * @since 2.3.0
 216  *
 217  * @param int $post_id
 218  * @return string|bool|WP_Error
 219  */
 220 function get_tags_to_edit( $post_id, $taxonomy = 'post_tag' ) {
 221         return get_terms_to_edit( $post_id, $taxonomy);
 222 }
 223
 224 /**
 225  * {@internal Missing Short Description}}
 226  *
 227  * @since 2.8.0
 228  *
 229  * @param int $post_id
 230  * @return string|bool|WP_Error
 231  */
 232 function get_terms_to_edit( $post_id, $taxonomy = 'post_tag' ) {
 233         $post_id = (int) $post_id;
 234         if ( !$post_id )
 235                 return false;
 236
 237         $terms = get_object_term_cache( $post_id, $taxonomy );
 238         if ( false === $terms ) {
 239                 $terms = wp_get_object_terms( $post_id, $taxonomy );
 240                 wp_cache_add( $post_id, $terms, $taxonomy . '_relationships' );
 241         }
 242
 243         if ( ! $terms ) {
 244                 return false;
 245         }
 246         if ( is_wp_error( $terms ) ) {
 247                 return $terms;
 248         }
 249         $term_names = array();
 250         foreach ( $terms as $term ) {
 251                 $term_names[] = $term->name;
 252         }
 253
 254         $terms_to_edit = esc_attr( join( ',', $term_names ) );
 255
 256         /**
 257          * Filter the comma-separated list of terms available to edit.
 258          *
 259          * @since 2.8.0
 260          *
 261          * @see get_terms_to_edit()
 262          *
 263          * @param array  $terms_to_edit An array of terms.
 264          * @param string $taxonomy     The taxonomy for which to retrieve terms. Default 'post_tag'.
 265          */
 266         $terms_to_edit = apply_filters( 'terms_to_edit', $terms_to_edit, $taxonomy );
 267
 268         return $terms_to_edit;
 269 }
 270
 271 /**
 272  * {@internal Missing Short Description}}
 273  *
 274  * @since 2.8.0
 275  *
 276  * @param int|string $tag_name
 277  * @return array|WP_Error
 278  */
 279 function wp_create_term($tag_name, $taxonomy = 'post_tag') {
 280         if ( $id = term_exists($tag_name, $taxonomy) )
 281                 return $id;
 282
 283         return wp_insert_term($tag_name, $taxonomy);
 284 }