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