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 unknown_type $cat_name
  19  * @return unknown
  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 unknown_type $id
  34  * @return unknown
  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 unknown_type $cat_name
  48  * @param unknown_type $parent
  49  * @return unknown
  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  * {@internal Missing Short Description}}
  60  *
  61  * @since 2.0.0
  62  *
  63  * @param unknown_type $categories
  64  * @param unknown_type $post_id
  65  * @return unknown
  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  *
  88  * @param mixed $catarr See defaults below. Set 'cat_ID' to a non-zero value to update an existing category. The 'taxonomy' key was added in 3.0.0.
  89  * @param bool $wp_error Optional, since 2.5.0. Set this to true if the caller handles WP_Error return values.
  90  * @return 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.
  91  */
  92 function wp_insert_category($catarr, $wp_error = false) {
  93         $cat_defaults = array('cat_ID' => 0, 'taxonomy' => 'category', 'cat_name' => '', 'category_description' => '', 'category_nicename' => '', 'category_parent' => '');
  94         $catarr = wp_parse_args($catarr, $cat_defaults);
  95         extract($catarr, EXTR_SKIP);
  96
  97         if ( trim( $cat_name ) == '' ) {
  98                 if ( ! $wp_error )
  99                         return 0;
 100                 else
 101                         return new WP_Error( 'cat_name', __('You did not enter a category name.') );
 102         }
 103
 104         $cat_ID = (int) $cat_ID;
 105
 106         // Are we updating or creating?
 107         if ( !empty ($cat_ID) )
 108                 $update = true;
 109         else
 110                 $update = false;
 111
 112         $name = $cat_name;
 113         $description = $category_description;
 114         $slug = $category_nicename;
 115         $parent = $category_parent;
 116
 117         $parent = (int) $parent;
 118         if ( $parent < 0 )
 119                 $parent = 0;
 120
 121         if ( empty( $parent ) || ! term_exists( $parent, $taxonomy ) || ( $cat_ID && term_is_ancestor_of( $cat_ID, $parent, $taxonomy ) ) )
 122                 $parent = 0;
 123
 124         $args = compact('name', 'slug', 'parent', 'description');
 125
 126         if ( $update )
 127                 $cat_ID = wp_update_term($cat_ID, $taxonomy, $args);
 128         else
 129                 $cat_ID = wp_insert_term($cat_name, $taxonomy, $args);
 130
 131         if ( is_wp_error($cat_ID) ) {
 132                 if ( $wp_error )
 133                         return $cat_ID;
 134                 else
 135                         return 0;
 136         }
 137
 138         return $cat_ID['term_id'];
 139 }
 140
 141 /**
 142  * Aliases wp_insert_category() with minimal args.
 143  *
 144  * If you want to update only some fields of an existing category, call this
 145  * function with only the new values set inside $catarr.
 146  *
 147  * @since 2.0.0
 148  *
 149  * @param array $catarr The 'cat_ID' value is required. All other keys are optional.
 150  * @return int|bool The ID number of the new or updated Category on success. Zero or FALSE on failure.
 151  */
 152 function wp_update_category($catarr) {
 153         $cat_ID = (int) $catarr['cat_ID'];
 154
 155         if ( isset($catarr['category_parent']) && ($cat_ID == $catarr['category_parent']) )
 156                 return false;
 157
 158         // First, get all of the original fields
 159         $category = get_term( $cat_ID, 'category', ARRAY_A );
 160         _make_cat_compat( $category );
 161
 162         // Escape data pulled from DB.
 163         $category = wp_slash($category);
 164
 165         // Merge old and new fields with new fields overwriting old ones.
 166         $catarr = array_merge($category, $catarr);
 167
 168         return wp_insert_category($catarr);
 169 }
 170
 171 //
 172 // Tags
 173 //
 174
 175 /**
 176  * {@internal Missing Short Description}}
 177  *
 178  * @since 2.3.0
 179  *
 180  * @param unknown_type $tag_name
 181  * @return unknown
 182  */
 183 function tag_exists($tag_name) {
 184         return term_exists($tag_name, 'post_tag');
 185 }
 186
 187 /**
 188  * {@internal Missing Short Description}}
 189  *
 190  * @since 2.3.0
 191  *
 192  * @param unknown_type $tag_name
 193  * @return unknown
 194  */
 195 function wp_create_tag($tag_name) {
 196         return wp_create_term( $tag_name, 'post_tag');
 197 }
 198
 199 /**
 200  * {@internal Missing Short Description}}
 201  *
 202  * @since 2.3.0
 203  *
 204  * @param unknown_type $post_id
 205  * @return unknown
 206  */
 207 function get_tags_to_edit( $post_id, $taxonomy = 'post_tag' ) {
 208         return get_terms_to_edit( $post_id, $taxonomy);
 209 }
 210
 211 /**
 212  * {@internal Missing Short Description}}
 213  *
 214  * @since 2.8.0
 215  *
 216  * @param unknown_type $post_id
 217  * @return unknown
 218  */
 219 function get_terms_to_edit( $post_id, $taxonomy = 'post_tag' ) {
 220         $post_id = (int) $post_id;
 221         if ( !$post_id )
 222                 return false;
 223
 224         $tags = wp_get_post_terms($post_id, $taxonomy, array());
 225
 226         if ( !$tags )
 227                 return false;
 228
 229         if ( is_wp_error($tags) )
 230                 return $tags;
 231
 232         foreach ( $tags as $tag )
 233                 $tag_names[] = $tag->name;
 234         $tags_to_edit = join( ',', $tag_names );
 235         $tags_to_edit = esc_attr( $tags_to_edit );
 236         $tags_to_edit = apply_filters( 'terms_to_edit', $tags_to_edit, $taxonomy );
 237
 238         return $tags_to_edit;
 239 }
 240
 241 /**
 242  * {@internal Missing Short Description}}
 243  *
 244  * @since 2.8.0
 245  *
 246  * @param unknown_type $tag_name
 247  * @return unknown
 248  */
 249 function wp_create_term($tag_name, $taxonomy = 'post_tag') {
 250         if ( $id = term_exists($tag_name, $taxonomy) )
 251                 return $id;
 252
 253         return wp_insert_term($tag_name, $taxonomy);
 254 }