9 // |
9 // |
10 // Category |
10 // Category |
11 // |
11 // |
12 |
12 |
13 /** |
13 /** |
14 * {@internal Missing Short Description}} |
14 * Check whether a category exists. |
15 * |
15 * |
16 * @since 2.0.0 |
16 * @since 2.0.0 |
17 * |
17 * |
18 * @param unknown_type $cat_name |
18 * @see term_exists() |
19 * @return unknown |
19 * |
20 */ |
20 * @param int|string $cat_name Category name. |
21 function category_exists($cat_name, $parent = 0) { |
21 * @param int $parent Optional. ID of parent term. |
|
22 * @return mixed |
|
23 */ |
|
24 function category_exists( $cat_name, $parent = null ) { |
22 $id = term_exists($cat_name, 'category', $parent); |
25 $id = term_exists($cat_name, 'category', $parent); |
23 if ( is_array($id) ) |
26 if ( is_array($id) ) |
24 $id = $id['term_id']; |
27 $id = $id['term_id']; |
25 return $id; |
28 return $id; |
26 } |
29 } |
27 |
30 |
28 /** |
31 /** |
29 * {@internal Missing Short Description}} |
32 * Get category object for given ID and 'edit' filter context. |
30 * |
33 * |
31 * @since 2.0.0 |
34 * @since 2.0.0 |
32 * |
35 * |
33 * @param unknown_type $id |
36 * @param int $id |
34 * @return unknown |
37 * @return object |
35 */ |
38 */ |
36 function get_category_to_edit( $id ) { |
39 function get_category_to_edit( $id ) { |
37 $category = get_term( $id, 'category', OBJECT, 'edit' ); |
40 $category = get_term( $id, 'category', OBJECT, 'edit' ); |
38 _make_cat_compat( $category ); |
41 _make_cat_compat( $category ); |
39 return $category; |
42 return $category; |
40 } |
43 } |
41 |
44 |
42 /** |
45 /** |
43 * {@internal Missing Short Description}} |
46 * Add a new category to the database if it does not already exist. |
44 * |
47 * |
45 * @since 2.0.0 |
48 * @since 2.0.0 |
46 * |
49 * |
47 * @param unknown_type $cat_name |
50 * @param int|string $cat_name |
48 * @param unknown_type $parent |
51 * @param int $parent |
49 * @return unknown |
52 * @return int|WP_Error |
50 */ |
53 */ |
51 function wp_create_category( $cat_name, $parent = 0 ) { |
54 function wp_create_category( $cat_name, $parent = 0 ) { |
52 if ( $id = category_exists($cat_name, $parent) ) |
55 if ( $id = category_exists($cat_name, $parent) ) |
53 return $id; |
56 return $id; |
54 |
57 |
55 return wp_insert_category( array('cat_name' => $cat_name, 'category_parent' => $parent) ); |
58 return wp_insert_category( array('cat_name' => $cat_name, 'category_parent' => $parent) ); |
56 } |
59 } |
57 |
60 |
58 /** |
61 /** |
59 * {@internal Missing Short Description}} |
62 * Create categories for the given post. |
60 * |
63 * |
61 * @since 2.0.0 |
64 * @since 2.0.0 |
62 * |
65 * |
63 * @param unknown_type $categories |
66 * @param array $categories List of categories to create. |
64 * @param unknown_type $post_id |
67 * @param int $post_id Optional. The post ID. Default empty. |
65 * @return unknown |
68 * @return List of categories to create for the given post. |
66 */ |
69 */ |
67 function wp_create_categories($categories, $post_id = '') { |
70 function wp_create_categories( $categories, $post_id = '' ) { |
68 $cat_ids = array (); |
71 $cat_ids = array (); |
69 foreach ($categories as $category) { |
72 foreach ( $categories as $category ) { |
70 if ($id = category_exists($category)) |
73 if ( $id = category_exists( $category ) ) { |
71 $cat_ids[] = $id; |
74 $cat_ids[] = $id; |
72 else |
75 } elseif ( $id = wp_create_category( $category ) ) { |
73 if ($id = wp_create_category($category)) |
76 $cat_ids[] = $id; |
74 $cat_ids[] = $id; |
77 } |
75 } |
78 } |
76 |
79 |
77 if ( $post_id ) |
80 if ( $post_id ) |
78 wp_set_post_categories($post_id, $cat_ids); |
81 wp_set_post_categories($post_id, $cat_ids); |
79 |
82 |
82 |
85 |
83 /** |
86 /** |
84 * Updates an existing Category or creates a new Category. |
87 * Updates an existing Category or creates a new Category. |
85 * |
88 * |
86 * @since 2.0.0 |
89 * @since 2.0.0 |
87 * |
90 * @since 2.5.0 $wp_error parameter was added. |
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. |
91 * @since 3.0.0 The 'taxonomy' argument was added. |
89 * @param bool $wp_error Optional, since 2.5.0. Set this to true if the caller handles WP_Error return values. |
92 * |
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. |
93 * @param array $catarr { |
91 */ |
94 * Array of arguments for inserting a new category. |
92 function wp_insert_category($catarr, $wp_error = false) { |
95 * |
93 $cat_defaults = array('cat_ID' => 0, 'taxonomy' => 'category', 'cat_name' => '', 'category_description' => '', 'category_nicename' => '', 'category_parent' => ''); |
96 * @type int $cat_ID Categoriy ID. A non-zero value updates an existing category. |
94 $catarr = wp_parse_args($catarr, $cat_defaults); |
97 * Default 0. |
95 extract($catarr, EXTR_SKIP); |
98 * @type string $taxonomy Taxonomy slug. Defualt 'category'. |
96 |
99 * @type string $cat_nam Category name. Default empty. |
97 if ( trim( $cat_name ) == '' ) { |
100 * @type string $category_description Category description. Default empty. |
98 if ( ! $wp_error ) |
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 ) { |
99 return 0; |
114 return 0; |
100 else |
115 } else { |
101 return new WP_Error( 'cat_name', __('You did not enter a category name.') ); |
116 return new WP_Error( 'cat_name', __( 'You did not enter a category name.' ) ); |
102 } |
117 } |
103 |
118 } |
104 $cat_ID = (int) $cat_ID; |
119 |
|
120 $catarr['cat_ID'] = (int) $catarr['cat_ID']; |
105 |
121 |
106 // Are we updating or creating? |
122 // Are we updating or creating? |
107 if ( !empty ($cat_ID) ) |
123 $update = ! empty ( $catarr['cat_ID'] ); |
108 $update = true; |
124 |
109 else |
125 $name = $catarr['cat_name']; |
110 $update = false; |
126 $description = $catarr['category_description']; |
111 |
127 $slug = $catarr['category_nicename']; |
112 $name = $cat_name; |
128 $parent = (int) $catarr['category_parent']; |
113 $description = $category_description; |
129 if ( $parent < 0 ) { |
114 $slug = $category_nicename; |
|
115 $parent = $category_parent; |
|
116 |
|
117 $parent = (int) $parent; |
|
118 if ( $parent < 0 ) |
|
119 $parent = 0; |
130 $parent = 0; |
120 |
131 } |
121 if ( empty( $parent ) || ! term_exists( $parent, $taxonomy ) || ( $cat_ID && term_is_ancestor_of( $cat_ID, $parent, $taxonomy ) ) ) |
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'] ) ) ) { |
122 $parent = 0; |
136 $parent = 0; |
|
137 } |
123 |
138 |
124 $args = compact('name', 'slug', 'parent', 'description'); |
139 $args = compact('name', 'slug', 'parent', 'description'); |
125 |
140 |
126 if ( $update ) |
141 if ( $update ) { |
127 $cat_ID = wp_update_term($cat_ID, $taxonomy, $args); |
142 $catarr['cat_ID'] = wp_update_term( $catarr['cat_ID'], $catarr['taxonomy'], $args ); |
128 else |
143 } else { |
129 $cat_ID = wp_insert_term($cat_name, $taxonomy, $args); |
144 $catarr['cat_ID'] = wp_insert_term( $catarr['cat_name'], $catarr['taxonomy'], $args ); |
130 |
145 } |
131 if ( is_wp_error($cat_ID) ) { |
146 |
132 if ( $wp_error ) |
147 if ( is_wp_error( $catarr['cat_ID'] ) ) { |
133 return $cat_ID; |
148 if ( $wp_error ) { |
134 else |
149 return $catarr['cat_ID']; |
|
150 } else { |
135 return 0; |
151 return 0; |
136 } |
152 } |
137 |
153 } |
138 return $cat_ID['term_id']; |
154 return $catarr['cat_ID']['term_id']; |
139 } |
155 } |
140 |
156 |
141 /** |
157 /** |
142 * Aliases wp_insert_category() with minimal args. |
158 * Aliases wp_insert_category() with minimal args. |
143 * |
159 * |
171 // |
187 // |
172 // Tags |
188 // Tags |
173 // |
189 // |
174 |
190 |
175 /** |
191 /** |
176 * {@internal Missing Short Description}} |
192 * Check whether a post tag with a given name exists. |
177 * |
193 * |
178 * @since 2.3.0 |
194 * @since 2.3.0 |
179 * |
195 * |
180 * @param unknown_type $tag_name |
196 * @param int|string $tag_name |
181 * @return unknown |
197 * @return mixed |
182 */ |
198 */ |
183 function tag_exists($tag_name) { |
199 function tag_exists($tag_name) { |
184 return term_exists($tag_name, 'post_tag'); |
200 return term_exists($tag_name, 'post_tag'); |
185 } |
201 } |
186 |
202 |
187 /** |
203 /** |
188 * {@internal Missing Short Description}} |
204 * Add a new tag to the database if it does not already exist. |
189 * |
205 * |
190 * @since 2.3.0 |
206 * @since 2.3.0 |
191 * |
207 * |
192 * @param unknown_type $tag_name |
208 * @param int|string $tag_name |
193 * @return unknown |
209 * @return array|WP_Error |
194 */ |
210 */ |
195 function wp_create_tag($tag_name) { |
211 function wp_create_tag($tag_name) { |
196 return wp_create_term( $tag_name, 'post_tag'); |
212 return wp_create_term( $tag_name, 'post_tag'); |
197 } |
213 } |
198 |
214 |
199 /** |
215 /** |
200 * {@internal Missing Short Description}} |
216 * Get comma-separated list of tags available to edit. |
201 * |
217 * |
202 * @since 2.3.0 |
218 * @since 2.3.0 |
203 * |
219 * |
204 * @param unknown_type $post_id |
220 * @param int $post_id |
205 * @return unknown |
221 * @param string $taxonomy Optional. The taxonomy for which to retrieve terms. Default 'post_tag'. |
|
222 * @return string|bool|WP_Error |
206 */ |
223 */ |
207 function get_tags_to_edit( $post_id, $taxonomy = 'post_tag' ) { |
224 function get_tags_to_edit( $post_id, $taxonomy = 'post_tag' ) { |
208 return get_terms_to_edit( $post_id, $taxonomy); |
225 return get_terms_to_edit( $post_id, $taxonomy); |
209 } |
226 } |
210 |
227 |
211 /** |
228 /** |
212 * {@internal Missing Short Description}} |
229 * Get comma-separated list of terms available to edit for the given post ID. |
213 * |
230 * |
214 * @since 2.8.0 |
231 * @since 2.8.0 |
215 * |
232 * |
216 * @param unknown_type $post_id |
233 * @param int $post_id |
217 * @return unknown |
234 * @param string $taxonomy Optional. The taxonomy for which to retrieve terms. Default 'post_tag'. |
|
235 * @return string|bool|WP_Error |
218 */ |
236 */ |
219 function get_terms_to_edit( $post_id, $taxonomy = 'post_tag' ) { |
237 function get_terms_to_edit( $post_id, $taxonomy = 'post_tag' ) { |
220 $post_id = (int) $post_id; |
238 $post_id = (int) $post_id; |
221 if ( !$post_id ) |
239 if ( !$post_id ) |
222 return false; |
240 return false; |
223 |
241 |
224 $tags = wp_get_post_terms($post_id, $taxonomy, array()); |
242 $terms = get_object_term_cache( $post_id, $taxonomy ); |
225 |
243 if ( false === $terms ) { |
226 if ( !$tags ) |
244 $terms = wp_get_object_terms( $post_id, $taxonomy ); |
|
245 wp_cache_add( $post_id, $terms, $taxonomy . '_relationships' ); |
|
246 } |
|
247 |
|
248 if ( ! $terms ) { |
227 return false; |
249 return false; |
228 |
250 } |
229 if ( is_wp_error($tags) ) |
251 if ( is_wp_error( $terms ) ) { |
230 return $tags; |
252 return $terms; |
231 |
253 } |
232 foreach ( $tags as $tag ) |
254 $term_names = array(); |
233 $tag_names[] = $tag->name; |
255 foreach ( $terms as $term ) { |
234 $tags_to_edit = join( ',', $tag_names ); |
256 $term_names[] = $term->name; |
235 $tags_to_edit = esc_attr( $tags_to_edit ); |
257 } |
236 $tags_to_edit = apply_filters( 'terms_to_edit', $tags_to_edit, $taxonomy ); |
258 |
237 |
259 $terms_to_edit = esc_attr( join( ',', $term_names ) ); |
238 return $tags_to_edit; |
260 |
239 } |
261 /** |
240 |
262 * Filter the comma-separated list of terms available to edit. |
241 /** |
263 * |
242 * {@internal Missing Short Description}} |
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. |
243 * |
278 * |
244 * @since 2.8.0 |
279 * @since 2.8.0 |
245 * |
280 * |
246 * @param unknown_type $tag_name |
281 * @param int|string $tag_name |
247 * @return unknown |
282 * @param string $taxonomy Optional. The taxonomy for which to retrieve terms. Default 'post_tag'. |
|
283 * @return array|WP_Error |
248 */ |
284 */ |
249 function wp_create_term($tag_name, $taxonomy = 'post_tag') { |
285 function wp_create_term($tag_name, $taxonomy = 'post_tag') { |
250 if ( $id = term_exists($tag_name, $taxonomy) ) |
286 if ( $id = term_exists($tag_name, $taxonomy) ) |
251 return $id; |
287 return $id; |
252 |
288 |