1<?php
  2/**
  3 * WordPress Taxonomy Administration API.
  4 *
  5 * @package WordPress
  6 * @subpackage Administration
  7 */
  8
  9//
 10// Category.
 11//
 12
 13/**
 14 * Checks 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        $category_parent Optional. ID of parent category.
 22 * @return string|null Returns the category ID as a numeric string if the pairing exists, null if not.
 23 */
 24function category_exists( $cat_name, $category_parent = null ) {
 25	$id = term_exists( $cat_name, 'category', $category_parent );
 26	if ( is_array( $id ) ) {
 27		$id = $id['term_id'];
 28	}
 29	return $id;
 30}
 31
 32/**
 33 * Gets category object for given ID and 'edit' filter context.
 34 *
 35 * @since 2.0.0
 36 *
 37 * @param int $id
 38 * @return object
 39 */
 40function 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 * Adds 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        Category name.
 52 * @param int        $category_parent Optional. ID of parent category.
 53 * @return int|WP_Error
 54 */
 55function wp_create_category( $cat_name, $category_parent = 0 ) {
 56	$id = category_exists( $cat_name, $category_parent );
 57	if ( $id ) {
 58		return $id;
 59	}
 60
 61	return wp_insert_category(
 62		array(
 63			'cat_name'        => $cat_name,
 64			'category_parent' => $category_parent,
 65		)
 66	);
 67}
 68
 69/**
 70 * Creates 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 */
 78function wp_create_categories( $categories, $post_id = 0 ) {
 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|WP_Error 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 */
121function 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 */
188function wp_update_category( $catarr ) {
189	$cat_id = (int) $catarr['cat_ID'];
190
191	if ( isset( $catarr['category_parent'] ) && ( $cat_id === (int) $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 * Checks 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 Returns null if the term does not exist.
219 *               Returns an array of the term ID and the term taxonomy ID if the pairing exists.
220 *               Returns 0 if term ID 0 is passed to the function.
221 */
222function tag_exists( $tag_name ) {
223	return term_exists( $tag_name, 'post_tag' );
224}
225
226/**
227 * Adds a new tag to the database if it does not already exist.
228 *
229 * @since 2.3.0
230 *
231 * @param int|string $tag_name
232 * @return array|WP_Error
233 */
234function wp_create_tag( $tag_name ) {
235	return wp_create_term( $tag_name, 'post_tag' );
236}
237
238/**
239 * Gets comma-separated list of tags available to edit.
240 *
241 * @since 2.3.0
242 *
243 * @param int    $post_id
244 * @param string $taxonomy Optional. The taxonomy for which to retrieve terms. Default 'post_tag'.
245 * @return string|false|WP_Error
246 */
247function get_tags_to_edit( $post_id, $taxonomy = 'post_tag' ) {
248	return get_terms_to_edit( $post_id, $taxonomy );
249}
250
251/**
252 * Gets comma-separated list of terms available to edit for the given post ID.
253 *
254 * @since 2.8.0
255 *
256 * @param int    $post_id
257 * @param string $taxonomy Optional. The taxonomy for which to retrieve terms. Default 'post_tag'.
258 * @return string|false|WP_Error
259 */
260function get_terms_to_edit( $post_id, $taxonomy = 'post_tag' ) {
261	$post_id = (int) $post_id;
262	if ( ! $post_id ) {
263		return false;
264	}
265
266	$terms = get_object_term_cache( $post_id, $taxonomy );
267	if ( false === $terms ) {
268		$terms = wp_get_object_terms( $post_id, $taxonomy );
269		wp_cache_add( $post_id, wp_list_pluck( $terms, 'term_id' ), $taxonomy . '_relationships' );
270	}
271
272	if ( ! $terms ) {
273		return false;
274	}
275	if ( is_wp_error( $terms ) ) {
276		return $terms;
277	}
278	$term_names = array();
279	foreach ( $terms as $term ) {
280		$term_names[] = $term->name;
281	}
282
283	$terms_to_edit = esc_attr( implode( ',', $term_names ) );
284
285	/**
286	 * Filters the comma-separated list of terms available to edit.
287	 *
288	 * @since 2.8.0
289	 *
290	 * @see get_terms_to_edit()
291	 *
292	 * @param string $terms_to_edit A comma-separated list of term names.
293	 * @param string $taxonomy      The taxonomy name for which to retrieve terms.
294	 */
295	$terms_to_edit = apply_filters( 'terms_to_edit', $terms_to_edit, $taxonomy );
296
297	return $terms_to_edit;
298}
299
300/**
301 * Adds a new term to the database if it does not already exist.
302 *
303 * @since 2.8.0
304 *
305 * @param string $tag_name The term name.
306 * @param string $taxonomy Optional. The taxonomy within which to create the term. Default 'post_tag'.
307 * @return array|WP_Error
308 */
309function wp_create_term( $tag_name, $taxonomy = 'post_tag' ) {
310	$id = term_exists( $tag_name, $taxonomy );
311	if ( $id ) {
312		return $id;
313	}
314
315	return wp_insert_term( $tag_name, $taxonomy );
316}
317