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