tring|WP_Error Array of terms, a count thereof as a numeric string, * or WP_Error if any of the taxonomies do not exist. * See the function description for more information. */ function get_terms( $args = array(), $deprecated = '' ) { $term_query = new WP_Term_Query(); $defaults = array( 'suppress_filter' => false, ); /* * Legacy argument format ($taxonomy, $args) takes precedence. * * We detect legacy argument format by checking if * (a) a second non-empty parameter is passed, or * (b) the first parameter shares no keys with the default array (ie, it's a list of taxonomies) */ $_args = wp_parse_args( $args ); $key_intersect = array_intersect_key( $term_query->query_var_defaults, (array) $_args ); $do_legacy_args = $deprecated || empty( $key_intersect ); if ( $do_legacy_args ) { $taxonomies = (array) $args; $args = wp_parse_args( $deprecated, $defaults ); $args['taxonomy'] = $taxonomies; } else { $args = wp_parse_args( $args, $defaults ); if ( isset( $args['taxonomy'] ) && null !== $args['taxonomy'] ) { $args['taxonomy'] = (array) $args['taxonomy']; } } if ( ! empty( $args['taxonomy'] ) ) { foreach ( $args['taxonomy'] as $taxonomy ) { if ( ! taxonomy_exists( $taxonomy ) ) { return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) ); } } } // Don't pass suppress_filter to WP_Term_Query. $suppress_filter = $args['suppress_filter']; unset( $args['suppress_filter'] ); $terms = $term_query->query( $args ); // Count queries are not filtered, for legacy reasons. if ( ! is_array( $terms ) ) { return $terms; } if ( $suppress_filter ) { return $terms; } /** * Filters the found terms. * * @since 2.3.0 * @since 4.6.0 Added the `$term_query` parameter. * * @param array $terms Array of found terms. * @param array|null $taxonomies An array of taxonomies if known. * @param array $args An array of get_terms() arguments. * @param WP_Term_Query $term_query The WP_Term_Query object. */ return apply_filters( 'get_terms', $terms, $term_query->query_vars['taxonomy'], $term_query->query_vars, $term_query ); } /** * Adds metadata to a term. * * @since 4.4.0 * * @param int $term_id Term ID. * @param string $meta_key Metadata name. * @param mixed $meta_value Metadata value. Must be serializable if non-scalar. * @param bool $unique Optional. Whether the same key should not be added. * Default false. * @return int|false|WP_Error Meta ID on success, false on failure. * WP_Error when term_id is ambiguous between taxonomies. */ function add_term_meta( $term_id, $meta_key, $meta_value, $unique = false ) { if ( wp_term_is_shared( $term_id ) ) { return new WP_Error( 'ambiguous_term_id', __( 'Term meta cannot be added to terms that are shared between taxonomies.' ), $term_id ); } return add_metadata( 'term', $term_id, $meta_key, $meta_value, $unique ); } /** * Removes metadata matching criteria from a term. * * @since 4.4.0 * * @param int $term_id Term ID. * @param string $meta_key Metadata name. * @param mixed $meta_value Optional. Metadata value. If provided, * rows will only be removed that match the value. * Must be serializable if non-scalar. Default empty. * @return bool True on success, false on failure. */ function delete_term_meta( $term_id, $meta_key, $meta_value = '' ) { return delete_metadata( 'term', $term_id, $meta_key, $meta_value ); } /** * Retrieves metadata for a term. * * @since 4.4.0 * * @param int $term_id Term ID. * @param string $key Optional. The meta key to retrieve. By default, * returns data for all keys. Default empty. * @param bool $single Optional. Whether to return a single value. * This parameter has no effect if `$key` is not specified. * Default false. * @return mixed An array of values if `$single` is false. * The value of the meta field if `$single` is true. * False for an invalid `$term_id` (non-numeric, zero, or negative value). * An empty string if a valid but non-existing term ID is passed. */ function get_term_meta( $term_id, $key = '', $single = false ) { return get_metadata( 'term', $term_id, $key, $single ); } /** * Updates term metadata. * * Use the `$prev_value` parameter to differentiate between meta fields with the same key and term ID. * * If the meta field for the term does not exist, it will be added. * * @since 4.4.0 * * @param int $term_id Term ID. * @param string $meta_key Metadata key. * @param mixed $meta_value Metadata value. Must be serializable if non-scalar. * @param mixed $prev_value Optional. Previous value to check before updating. * If specified, only update existing metadata entries with * this value. Otherwise, update all entries. Default empty. * @return int|bool|WP_Error Meta ID if the key didn't exist. true on successful update, * false on failure or if the value passed to the function * is the same as the one that is already in the database. * WP_Error when term_id is ambiguous between taxonomies. */ function update_term_meta( $term_id, $meta_key, $meta_value, $prev_value = '' ) { if ( wp_term_is_shared( $term_id ) ) { return new WP_Error( 'ambiguous_term_id', __( 'Term meta cannot be added to terms that are shared between taxonomies.' ), $term_id ); } return update_metadata( 'term', $term_id, $meta_key, $meta_value, $prev_value ); } /** * Updates metadata cache for list of term IDs. * * Performs SQL query to retrieve all metadata for the terms matching `$term_ids` and stores them in the cache. * Subsequent calls to `get_term_meta()` will not need to query the database. * * @since 4.4.0 * * @param array $term_ids List of term IDs. * @return array|false An array of metadata on success, false if there is nothing to update. */ function update_termmeta_cache( $term_ids ) { return update_meta_cache( 'term', $term_ids ); } /** * Gets all meta data, including meta IDs, for the given term ID. * * @since 4.9.0 * * @global wpdb $wpdb WordPress database abstraction object. * * @param int $term_id Term ID. * @return array|false Array with meta data, or false when the meta table is not installed. */ function has_term_meta( $term_id ) { $check = wp_check_term_meta_support_prefilter( null ); if ( null !== $check ) { return $check; } global $wpdb; return $wpdb->get_results( $wpdb->prepare( "SELECT meta_key, meta_value, meta_id, term_id FROM $wpdb->termmeta WHERE term_id = %d ORDER BY meta_key,meta_id", $term_id ), ARRAY_A ); } /** * Registers a meta key for terms. * * @since 4.9.8 * * @param string $taxonomy Taxonomy to register a meta key for. Pass an empty string * to register the meta key across all existing taxonomies. * @param string $meta_key The meta key to register. * @param array $args Data used to describe the meta key when registered. See * {@see register_meta()} for a list of supported arguments. * @return bool True if the meta key was successfully registered, false if not. */ function register_term_meta( $taxonomy, $meta_key, array $args ) { $args['object_subtype'] = $taxonomy; return register_meta( 'term', $meta_key, $args ); } /** * Unregisters a meta key for terms. * * @since 4.9.8 * * @param string $taxonomy Taxonomy the meta key is currently registered for. Pass * an empty string if the meta key is registered across all * existing taxonomies. * @param string $meta_key The meta key to unregister. * @return bool True on success, false if the meta key was not previously registered. */ function unregister_term_meta( $taxonomy, $meta_key ) { return unregister_meta_key( 'term', $meta_key, $taxonomy ); } /** * Determines whether a taxonomy term exists. * * Formerly is_term(), introduced in 2.3.0. * * For more information on this and similar theme functions, check out * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ * Conditional Tags} article in the Theme Developer Handbook. * * @since 3.0.0 * @since 6.0.0 Converted to use `get_terms()`. * * @global bool $_wp_suspend_cache_invalidation * * @param int|string $term The term to check. Accepts term ID, slug, or name. * @param string $taxonomy Optional. The taxonomy name to use. * @param int $parent_term Optional. ID of parent term under which to confine the exists search. * @return mixed Returns null if the term does not exist. * Returns the term ID if no taxonomy is specified and the term ID exists. * Returns an array of the term ID and the term taxonomy ID if the taxonomy is specified and the pairing exists. * Returns 0 if term ID 0 is passed to the function. */ function term_exists( $term, $taxonomy = '', $parent_term = null ) { global $_wp_suspend_cache_invalidation; if ( null === $term ) { return null; } $defaults = array( 'get' => 'all', 'fields' => 'ids', 'number' => 1, 'update_term_meta_cache' => false, 'order' => 'ASC', 'orderby' => 'term_id', 'suppress_filter' => true, ); // Ensure that while importing, queries are not cached. if ( ! empty( $_wp_suspend_cache_invalidation ) ) { // @todo Disable caching once #52710 is merged. $defaults['cache_domain'] = microtime(); } if ( ! empty( $taxonomy ) ) { $defaults['taxonomy'] = $taxonomy; $defaults['fields'] = 'all'; } /** * Filters default query arguments for checking if a term exists. * * @since 6.0.0 * * @param array $defaults An array of arguments passed to get_terms(). * @param int|string $term The term to check. Accepts term ID, slug, or name. * @param string $taxonomy The taxonomy name to use. An empty string indicates * the search is against all taxonomies. * @param int|null $parent_term ID of parent term under which to confine the exists search. * Null indicates the search is unconfined. */ $defaults = apply_filters( 'term_exists_default_query_args', $defaults, $term, $taxonomy, $parent_term ); if ( is_int( $term ) ) { if ( 0 === $term ) { return 0; } $args = wp_parse_args( array( 'include' => array( $term ) ), $defaults ); $terms = get_terms( $args ); } else { $term = trim( wp_unslash( $term ) ); if ( '' === $term ) { return null; } if ( ! empty( $taxonomy ) && is_numeric( $parent_term ) ) { $defaults['parent'] = (int) $parent_term; } $args = wp_parse_args( array( 'slug' => sanitize_title( $term ) ), $defaults ); $terms = get_terms( $args ); if ( empty( $terms ) || is_wp_error( $terms ) ) { $args = wp_parse_args( array( 'name' => $term ), $defaults ); $terms = get_terms( $args ); } } if ( empty( $terms ) || is_wp_error( $terms ) ) { return null; } $_term = array_shift( $terms ); if ( ! empty( $taxonomy ) ) { return array( 'term_id' => (string) $_term->term_id, 'term_taxonomy_id' => (string) $_term->term_taxonomy_id, ); } return (string) $_term; } /** * Checks if a term is an ancestor of another term. * * You can use either an ID or the term object for both parameters. * * @since 3.4.0 * * @param int|object $term1 ID or object to check if this is the parent term. * @param int|object $term2 The child term. * @param string $taxonomy Taxonomy name that $term1 and `$term2` belong to. * @return bool Whether `$term2` is a child of `$term1`. */ function term_is_ancestor_of( $term1, $term2, $taxonomy ) { if ( ! isset( $term1->term_id ) ) { $term1 = get_term( $term1, $taxonomy ); } if ( ! isset( $term2->parent ) ) { $term2 = get_term( $term2, $taxonomy ); } if ( empty( $term1->term_id ) || empty( $term2->parent ) ) { return false; } if ( $term2->parent === $term1->term_id ) { return true; } return term_is_ancestor_of( $term1, get_term( $term2->parent, $taxonomy ), $taxonomy ); } /** * Sanitizes all term fields. * * Relies on sanitize_term_field() to sanitize the term. The difference is that * this function will sanitize **all** fields. The context is based * on sanitize_term_field(). * * The `$term` is expected to be either an array or an object. * * @since 2.3.0 * * @param array|object $term The term to check. * @param string $taxonomy The taxonomy name to use. * @param string $context Optional. Context in which to sanitize the term. * Accepts 'raw', 'edit', 'db', 'display', 'rss', * 'attribute', or 'js'. Default 'display'. * @return array|object Term with all fields sanitized. */ function sanitize_term( $term, $taxonomy, $context = 'display' ) { $fields = array( 'term_id', 'name', 'description', 'slug', 'count', 'parent', 'term_group', 'term_taxonomy_id', 'object_id' ); $do_object = is_object( $term ); $term_id = $do_object ? $term->term_id : ( isset( $term['term_id'] ) ? $term['term_id'] : 0 ); foreach ( (array) $fields as $field ) { if ( $do_object ) { if ( isset( $term->$field ) ) { $term->$field = sanitize_term_field( $field, $term->$field, $term_id, $taxonomy, $context ); } } else { if ( isset( $term[ $field ] ) ) { $term[ $field ] = sanitize_term_field( $field, $term[ $field ], $term_id, $taxonomy, $context ); } } } if ( $do_object ) { $term->filter = $context; } else { $term['filter'] = $context; } return $term; } /** * Sanitizes the field value in the term based on the context. * * Passing a term field value through the function should be assumed to have * cleansed the value for whatever context the term field is going to be used. * * If no context or an unsupported context is given, then default filters will * be applied. * * There are enough filters for each context to support a custom filtering * without creating your own filter function. Simply create a function that * hooks into the filter you need. * * @since 2.3.0 * * @param string $field Term field to sanitize. * @param string $value Search for this term value. * @param int $term_id Term ID. * @param string $taxonomy Taxonomy name. * @param string $context Context in which to sanitize the term field. * Accepts 'raw', 'edit', 'db', 'display', 'rss', * 'attribute', or 'js'. Default 'display'. * @return mixed Sanitized field. */ function sanitize_term_field( $field, $value, $term_id, $taxonomy, $context ) { $int_fields = array( 'parent', 'term_id', 'count', 'term_group', 'term_taxonomy_id', 'object_id' ); if ( in_array( $field, $int_fields, true ) ) { $value = (int) $value; if ( $value < 0 ) { $value = 0; } } $context = strtolower( $context ); if ( 'raw' === $context ) { return $value; } if ( 'edit' === $context ) { /** * Filters a term field to edit before it is sanitized. * * The dynamic portion of the hook name, `$field`, refers to the term field. * * @since 2.3.0 * * @param mixed $value Value of the term field. * @param int $term_id Term ID. * @param string $taxonomy Taxonomy slug. */ $value = apply_filters( "edit_term_{$field}", $value, $term_id, $taxonomy ); /** * Filters the taxonomy field to edit before it is sanitized. * * The dynamic portions of the filter name, `$taxonomy` and `$field`, refer * to the taxonomy slug and taxonomy field, respectively. * * @since 2.3.0 * * @param mixed $value Value of the taxonomy field to edit. * @param int $term_id Term ID. */ $value = apply_filters( "edit_{$taxonomy}_{$field}", $value, $term_id ); if ( 'description' === $field ) { $value = esc_html( $value ); // textarea_escaped } else { $value = esc_attr( $value ); } } elseif ( 'db' === $context ) { /** * Filters a term field value before it is sanitized. * * The dynamic portion of the hook name, `$field`, refers to the term field. * * @since 2.3.0 * * @param mixed $value Value of the term field. * @param string $taxonomy Taxonomy slug. */ $value = apply_filters( "pre_term_{$field}", $value, $taxonomy ); /** * Filters a taxonomy field before it is sanitized. * * The dynamic portions of the filter name, `$taxonomy` and `$field`, refer * to the taxonomy slug and field name, respectively. * * @since 2.3.0 * * @param mixed $value Value of the taxonomy field. */ $value = apply_filters( "pre_{$taxonomy}_{$field}", $value ); // Back compat filters. if ( 'slug' === $field ) { /** * Filters the category nicename before it is sanitized. * * Use the {@see 'pre_$taxonomy_$field'} hook instead. * * @since 2.0.3 * * @param string $value The category nicename. */ $value = apply_filters( 'pre_category_nicename', $value ); } } elseif ( 'rss' === $context ) { /** * Filters the term field for use in RSS. * * The dynamic portion of the hook name, `$field`, refers to the term field. * * @since 2.3.0 * * @param mixed $value Value of the term field. * @param string $taxonomy Taxonomy slug. */ $value = apply_filters( "term_{$field}_rss", $value, $taxonomy ); /** * Filters the taxonomy field for use in RSS. * * The dynamic portions of the hook name, `$taxonomy`, and `$field`, refer * to the taxonomy slug and field name, respectively. * * @since 2.3.0 * * @param mixed $value Value of the taxonomy field. */ $value = apply_filters( "{$taxonomy}_{$field}_rss", $value ); } else { // Use display filters by default. /** * Filters the term field sanitized for display. * * The dynamic portion of the hook name, `$field`, refers to the term field name. * * @since 2.3.0 * * @param mixed $value Value of the term field. * @param int $term_id Term ID. * @param string $taxonomy Taxonomy slug. * @param string $context Context to retrieve the term field value. */ $value = apply_filters( "term_{$field}", $value, $term_id, $taxonomy, $context ); /** * Filters the taxonomy field sanitized for display. * * The dynamic portions of the filter name, `$taxonomy`, and `$field`, refer * to the taxonomy slug and taxonomy field, respectively. * * @since 2.3.0 * * @param mixed $value Value of the taxonomy field. * @param int $term_id Term ID. * @param string $context Context to retrieve the taxonomy field value. */ $value = apply_filters( "{$taxonomy}_{$field}", $value, $term_id, $context ); } if ( 'attribute' === $context ) { $value = esc_attr( $value ); } elseif ( 'js' === $context ) { $value = esc_js( $value ); } // Restore the type for integer fields after esc_attr(). if ( in_array( $field, $int_fields, true ) ) { $value = (int) $value; } return $value; } /** * Counts how many terms are in taxonomy. * * Default $args is 'hide_empty' which can be 'hide_empty=true' or array('hide_empty' => true). * * @since 2.3.0 * @since 5.6.0 Changed the function signature so that the `$args` array can be provided as the first parameter. * * @internal The `$deprecated` parameter is parsed for backward compatibility only. * * @param array|string $args Optional. Array or string of arguments. See WP_Term_Query::__construct() * for information on accepted arguments. Default empty array. * @param array|string $deprecated Optional. Argument array, when using the legacy function parameter format. * If present, this parameter will be interpreted as `$args`, and the first * function parameter will be parsed as a taxonomy or array of taxonomies. * Default empty. * @return string|WP_Error Numeric string containing the number of terms in that * taxonomy or WP_Error if the taxonomy does not exist. */ function wp_count_terms( $args = array(), $deprecated = '' ) { $use_legacy_args = false; // Check whether function is used with legacy signature: `$taxonomy` and `$args`. if ( $args && ( is_string( $args ) && taxonomy_exists( $args ) || is_array( $args ) && wp_is_numeric_array( $args ) ) ) { $use_legacy_args = true; } $defaults = array( 'hide_empty' => false ); if ( $use_legacy_args ) { $defaults['taxonomy'] = $args; $args = $deprecated; } $args = wp_parse_args( $args, $defaults ); // Backward compatibility. if ( isset( $args['ignore_empty'] ) ) { $args['hide_empty'] = $args['ignore_empty']; unset( $args['ignore_empty'] ); } $args['fields'] = 'count'; return get_terms( $args ); } /** * Unlinks the object from the taxonomy or taxonomies. * * Will remove all relationships between the object and any terms in * a particular taxonomy or taxonomies. Does not remove the term or * taxonomy itself. * * @since 2.3.0 * * @param int $object_id The term object ID that refers to the term. * @param string|array $taxonomies List of taxonomy names or single taxonomy name. */ function wp_delete_object_term_relationships( $object_id, $taxonomies ) { $object_id = (int) $object_id; if ( ! is_array( $taxonomies ) ) { $taxonomies = array( $taxonomies ); } foreach ( (array) $taxonomies as $taxonomy ) { $term_ids = wp_get_object_terms( $object_id, $taxonomy, array( 'fields' => 'ids' ) ); $term_ids = array_map( 'intval', $term_ids ); wp_remove_object_terms( $object_id, $term_ids, $taxonomy ); } } /** * Removes a term from the database. * * If the term is a parent of other terms, then the children will be updated to * that term's parent. * * Metadata associated with the term will be deleted. * * @since 2.3.0 * * @global wpdb $wpdb WordPress database abstraction object. * * @param int $term Term ID. * @param string $taxonomy Taxonomy name. * @param array|string $args { * Optional. Array of arguments to override the default term ID. Default empty array. * * @type int $default The term ID to make the default term. This will only override * the terms found if there is only one term found. Any other and * the found terms are used. * @type bool $force_default Optional. Whether to force the supplied term as default to be * assigned even if the object was not going to be term-less. * Default false. * } * @return bool|int|WP_Error True on success, false if term does not exist. Zero on attempted * deletion of default Category. WP_Error if the taxonomy does not exist. */ function wp_delete_term( $term, $taxonomy, $args = array() ) { global $wpdb; $term = (int) $term; $ids = term_exists( $term, $taxonomy ); if ( ! $ids ) { return false; } if ( is_wp_error( $ids ) ) { return $ids; } $tt_id = $ids['term_taxonomy_id']; $defaults = array(); if ( 'category' === $taxonomy ) { $defaults['default'] = (int) get_option( 'default_category' ); if ( $defaults['default'] === $term ) { return 0; // Don't delete the default category. } } // Don't delete the default custom taxonomy term. $taxonomy_object = get_taxonomy( $taxonomy ); if ( ! empty( $taxonomy_object->default_term ) ) { $defaults['default'] = (int) get_option( 'default_term_' . $taxonomy ); if ( $defaults['default'] === $term ) { return 0; } } $args = wp_parse_args( $args, $defaults ); if ( isset( $args['default'] ) ) { $default = (int) $args['default']; if ( ! term_exists( $default, $taxonomy ) ) { unset( $default ); } } if ( isset( $args['force_default'] ) ) { $force_default = $args['force_default']; } /** * Fires when deleting a term, before any modifications are made to posts or terms. * * @since 4.1.0 * * @param int $term Term ID. * @param string $taxonomy Taxonomy name. */ do_action( 'pre_delete_term', $term, $taxonomy ); // Update children to point to new parent. if ( is_taxonomy_hierarchical( $taxonomy ) ) { $term_obj = get_term( $term, $taxonomy ); if ( is_wp_error( $term_obj ) ) { return $term_obj; } $parent = $term_obj->parent; $edit_ids = $wpdb->get_results( "SELECT term_id, term_taxonomy_id FROM $wpdb->term_taxonomy WHERE `parent` = " . (int) $term_obj->term_id ); $edit_tt_ids = wp_list_pluck( $edit_ids, 'term_taxonomy_id' ); /** * Fires immediately before a term to delete's children are reassigned a parent. * * @since 2.9.0 * * @param array $edit_tt_ids An array of term taxonomy IDs for the given term. */ do_action( 'edit_term_taxonomies', $edit_tt_ids ); $wpdb->update( $wpdb->term_taxonomy, compact( 'parent' ), array( 'parent' => $term_obj->term_id ) + compact( 'taxonomy' ) ); // Clean the cache for all child terms. $edit_term_ids = wp_list_pluck( $edit_ids, 'term_id' ); clean_term_cache( $edit_term_ids, $taxonomy ); /** * Fires immediately after a term to delete's children are reassigned a parent. * * @since 2.9.0 * * @param array $edit_tt_ids An array of term taxonomy IDs for the given term. */ do_action( 'edited_term_taxonomies', $edit_tt_ids ); } // Get the term before deleting it or its term relationships so we can pass to actions below. $deleted_term = get_term( $term, $taxonomy ); $object_ids = (array) $wpdb->get_col( $wpdb->prepare( "SELECT object_id FROM $wpdb->term_relationships WHERE term_taxonomy_id = %d", $tt_id ) ); foreach ( $object_ids as $object_id ) { if ( ! isset( $default ) ) { wp_remove_object_terms( $object_id, $term, $taxonomy ); continue; } $terms = wp_get_object_terms( $object_id, $taxonomy, array( 'fields' => 'ids', 'orderby' => 'none', ) ); if ( 1 === count( $terms ) && isset( $default ) ) { $terms = array( $default ); } else { $terms = array_diff( $terms, array( $term ) ); if ( isset( $default ) && isset( $force_default ) && $force_default ) { $terms = array_merge( $terms, array( $default ) ); } } $terms = array_map( 'intval', $terms ); wp_set_object_terms( $object_id, $terms, $taxonomy ); } // Clean the relationship caches for all object types using this term. $tax_object = get_taxonomy( $taxonomy ); foreach ( $tax_object->object_type as $object_type ) { clean_object_term_cache( $object_ids, $object_type ); } $term_meta_ids = $wpdb->get_col( $wpdb->prepare( "SELECT meta_id FROM $wpdb->termmeta WHERE term_id = %d ", $term ) ); foreach ( $term_meta_ids as $mid ) { delete_metadata_by_mid( 'term', $mid ); } /** * Fires immediately before a term taxonomy ID is deleted. * * @since 2.9.0 * * @param int $tt_id Term taxonomy ID. */ do_action( 'delete_term_taxonomy', $tt_id ); $wpdb->delete( $wpdb->term_taxonomy, array( 'term_taxonomy_id' => $tt_id ) ); /** * Fires immediately after a term taxonomy ID is deleted. * * @since 2.9.0 * * @param int $tt_id Term taxonomy ID. */ do_action( 'deleted_term_taxonomy', $tt_id ); // Delete the term if no taxonomies use it. if ( ! $wpdb->get_var( $wpdb->prepare( "SELECT COUNT(*) FROM $wpdb->term_taxonomy WHERE term_id = %d", $term ) ) ) { $wpdb->delete( $wpdb->terms, array( 'term_id' => $term ) ); } clean_term_cache( $term, $taxonomy ); /** * Fires after a term is deleted from the database and the cache is cleaned. * * The {@see 'delete_$taxonomy'} hook is also available for targeting a specific * taxonomy. * * @since 2.5.0 * @since 4.5.0 Introduced the `$object_ids` argument. * * @param int $term Term ID. * @param int $tt_id Term taxonomy ID. * @param string $taxonomy Taxonomy slug. * @param WP_Term $deleted_term Copy of the already-deleted term. * @param array $object_ids List of term object IDs. */ do_action( 'delete_term', $term, $tt_id, $taxonomy, $deleted_term, $object_ids ); /** * Fires after a term in a specific taxonomy is deleted. * * The dynamic portion of the hook name, `$taxonomy`, refers to the specific * taxonomy the term belonged to. * * Possible hook names include: * * - `delete_category` * - `delete_post_tag` * * @since 2.3.0 * @since 4.5.0 Introduced the `$object_ids` argument. * * @param int $term Term ID. * @param int $tt_id Term taxonomy ID. * @param WP_Term $deleted_term Copy of the already-deleted term. * @param array $object_ids List of term object IDs. */ do_action( "delete_{$taxonomy}", $term, $tt_id, $deleted_term, $object_ids ); return true; } /** * Deletes one existing category. * * @since 2.0.0 * * @param int $cat_id Category term ID. * @return bool|int|WP_Error Returns true if completes delete action; false if term doesn't exist; * Zero on attempted deletion of default Category; WP_Error object is * also a possibility. */ function wp_delete_category( $cat_id ) { return wp_delete_term( $cat_id, 'category' ); } /** * Retrieves the terms associated with the given object(s), in the supplied taxonomies. * * @since 2.3.0 * @since 4.2.0 Added support for 'taxonomy', 'parent', and 'term_taxonomy_id' values of `$orderby`. * Introduced `$parent` argument. * @since 4.4.0 Introduced `$meta_query` and `$update_term_meta_cache` arguments. When `$fields` is 'all' or * 'all_with_object_id', an array of `WP_Term` objects will be returned. * @since 4.7.0 Refactored to use WP_Term_Query, and to support any WP_Term_Query arguments. * * @param int|int[] $object_ids The ID(s) of the object(s) to retrieve. * @param string|string[] $taxonomies The taxonomy names to retrieve terms from. * @param array|string $args See WP_Term_Query::__construct() for supported arguments. * @return WP_Term[]|int[]|string[]|string|WP_Error Array of terms, a count thereof as a numeric string, * or WP_Error if any of the taxonomies do not exist. * See WP_Term_Query::get_terms() for more information. */ function wp_get_object_terms( $object_ids, $taxonomies, $args = array() ) { if ( empty( $object_ids ) || empty( $taxonomies ) ) { return array(); } if ( ! is_array( $taxonomies ) ) { $taxonomies = array( $taxonomies ); } foreach ( $taxonomies as $taxonomy ) { if ( ! taxonomy_exists( $taxonomy ) ) { return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) ); } } if ( ! is_array( $object_ids ) ) { $object_ids = array( $object_ids ); } $object_ids = array_map( 'intval', $object_ids ); $args = wp_parse_args( $args ); /** * Filters arguments for retrieving object terms. * * @since 4.9.0 * * @param array $args An array of arguments for retrieving terms for the given object(s). * See {@see wp_get_object_terms()} for details. * @param int[] $object_ids Array of object IDs. * @param string[] $taxonomies Array of taxonomy names to retrieve terms from. */ $args = apply_filters( 'wp_get_object_terms_args', $args, $object_ids, $taxonomies ); /* * When one or more queried taxonomies is registered with an 'args' array, * those params override the `$args` passed to this function. */ $terms = array(); if ( count( $taxonomies ) > 1 ) { foreach ( $taxonomies as $index => $taxonomy ) { $t = get_taxonomy( $taxonomy ); if ( isset( $t->args ) && is_array( $t->args ) && array_merge( $args, $t->args ) != $args ) { unset( $taxonomies[ $index ] ); $terms = array_merge( $terms, wp_get_object_terms( $object_ids, $taxonomy, array_merge( $args, $t->args ) ) ); } } } else { $t = get_taxonomy( $taxonomies[0] ); if ( isset( $t->args ) && is_array( $t->args ) ) { $args = array_merge( $args, $t->args ); } } $args['taxonomy'] = $taxonomies; $args['object_ids'] = $object_ids; // Taxonomies registered without an 'args' param are handled here. if ( ! empty( $taxonomies ) ) { $terms_from_remaining_taxonomies = get_terms( $args ); // Array keys should be preserved for values of $fields that use term_id for keys. if ( ! empty( $args['fields'] ) && 0 === strpos( $args['fields'], 'id=>' ) ) { $terms = $terms + $terms_from_remaining_taxonomies; } else { $terms = array_merge( $terms, $terms_from_remaining_taxonomies ); } } /** * Filters the terms for a given object or objects. * * @since 4.2.0 * * @param WP_Term[]|int[]|string[]|string $terms Array of terms or a count thereof as a numeric string. * @param int[] $object_ids Array of object IDs for which terms were retrieved. * @param string[] $taxonomies Array of taxonomy names from which terms were retrieved. * @param array $args Array of arguments for retrieving terms for the given * object(s). See wp_get_object_terms() for details. */ $terms = apply_filters( 'get_object_terms', $terms, $object_ids, $taxonomies, $args ); $object_ids = implode( ',', $object_ids ); $taxonomies = "'" . implode( "', '", array_map( 'esc_sql', $taxonomies ) ) . "'"; /** * Filters the terms for a given object or objects. * * The `$taxonomies` parameter passed to this filter is formatted as a SQL fragment. The * {@see 'get_object_terms'} filter is recommended as an alternative. * * @since 2.8.0 * * @param WP_Term[]|int[]|string[]|string $terms Array of terms or a count thereof as a numeric string. * @param string $object_ids Comma separated list of object IDs for which terms were retrieved. * @param string $taxonomies SQL fragment of taxonomy names from which terms were retrieved. * @param array $args Array of arguments for retrieving terms for the given * object(s). See wp_get_object_terms() for details. */ return apply_filters( 'wp_get_object_terms', $terms, $object_ids, $taxonomies, $args ); } /** * Adds a new term to the database. * * A non-existent term is inserted in the following sequence: * 1. The term is added to the term table, then related to the taxonomy. * 2. If everything is correct, several actions are fired. * 3. The 'term_id_filter' is evaluated. * 4. The term cache is cleaned. * 5. Several more actions are fired. * 6. An array is returned containing the `term_id` and `term_taxonomy_id`. * * If the 'slug' argument is not empty, then it is checked to see if the term * is invalid. If it is not a valid, existing term, it is added and the term_id * is given. * * If the taxonomy is hierarchical, and the 'parent' argument is not empty, * the term is inserted and the term_id will be given. * * Error handling: * If `$taxonomy` does not exist or `$term` is empty, * a WP_Error object will be returned. * * If the term already exists on the same hierarchical level, * or the term slug and name are not unique, a WP_Error object will be returned. * * @global wpdb $wpdb WordPress database abstraction object. * * @since 2.3.0 * * @param string $term The term name to add. * @param string $taxonomy The taxonomy to which to add the term. * @param array|string $args { * Optional. Array or query string of arguments for inserting a term. * * @type string $alias_of Slug of the term to make this term an alias of. * Default empty string. Accepts a term slug. * @type string $description The term description. Default empty string. * @type int $parent The id of the parent term. Default 0. * @type string $slug The term slug to use. Default empty string. * } * @return array|WP_Error { * An array of the new term data, WP_Error otherwise. * * @type int $term_id The new term ID. * @type int|string $term_taxonomy_id The new term taxonomy ID. Can be a numeric string. * } */ function wp_insert_term( $term, $taxonomy, $args = array() ) { global $wpdb; if ( ! taxonomy_exists( $taxonomy ) ) { return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) ); } /** * Filters a term before it is sanitized and inserted into the database. * * @since 3.0.0 * @since 6.1.0 The `$args` parameter was added. * * @param string|WP_Error $term The term name to add, or a WP_Error object if there's an error. * @param string $taxonomy Taxonomy slug. * @param array|string $args Array or query string of arguments passed to wp_insert_term(). */ $term = apply_filters( 'pre_insert_term', $term, $taxonomy, $args ); if ( is_wp_error( $term ) ) { return $term; } if ( is_int( $term ) && 0 === $term ) { return new WP_Error( 'invalid_term_id', __( 'Invalid term ID.' ) ); } if ( '' === trim( $term ) ) { return new WP_Error( 'empty_term_name', __( 'A name is required for this term.' ) ); } $defaults = array( 'alias_of' => '', 'description' => '', 'parent' => 0, 'slug' => '', ); $args = wp_parse_args( $args, $defaults ); if ( (int) $args['parent'] > 0 && ! term_exists( (int) $args['parent'] ) ) { return new WP_Error( 'missing_parent', __( 'Parent term does not exist.' ) ); } $args['name'] = $term; $args['taxonomy'] = $taxonomy; // Coerce null description to strings, to avoid database errors. $args['description'] = (string) $args['description']; $args = sanitize_term( $args, $taxonomy, 'db' ); // expected_slashed ($name) $name = wp_unslash( $args['name'] ); $description = wp_unslash( $args['description'] ); $parent = (int) $args['parent']; $slug_provided = ! empty( $args['slug'] ); if ( ! $slug_provided ) { $slug = sanitize_title( $name ); } else { $slug = $args['slug']; } $term_group = 0; if ( $args['alias_of'] ) { $alias = get_term_by( 'slug', $args['alias_of'], $taxonomy ); if ( ! empty( $alias->term_group ) ) { // The alias we want is already in a group, so let's use that one. $term_group = $alias->term_group; } elseif ( ! empty( $alias->term_id ) ) { /* * The alias is not in a group, so we create a new one * and add the alias to it. */ $term_group = $wpdb->get_var( "SELECT MAX(term_group) FROM $wpdb->terms" ) + 1; wp_update_term( $alias->term_id, $taxonomy, array( 'term_group' => $term_group, ) ); } } /* * Prevent the creation of terms with duplicate names at the same level of a taxonomy hierarchy, * unless a unique slug has been explicitly provided. */ $name_matches = get_terms( array( 'taxonomy' => $taxonomy, 'name' => $name, 'hide_empty' => false, 'parent' => $args['parent'], 'update_term_meta_cache' => false, ) ); /* * The `name` match in `get_terms()` doesn't differentiate accented characters, * so we do a stricter comparison here. */ $name_match = null; if ( $name_matches ) { foreach ( $name_matches as $_match ) { if ( strtolower( $name ) === strtolower( $_match->name ) ) { $name_match = $_match; break; } } } if ( $name_match ) { $slug_match = get_term_by( 'slug', $slug, $taxonomy ); if ( ! $slug_provided || $name_match->slug === $slug || $slug_match ) { if ( is_taxonomy_hierarchical( $taxonomy ) ) { $siblings = get_terms( array( 'taxonomy' => $taxonomy, 'get' => 'all', 'parent' => $parent, 'update_term_meta_cache' => false, ) ); $existing_term = null; $sibling_names = wp_list_pluck( $siblings, 'name' ); $sibling_slugs = wp_list_pluck( $siblings, 'slug' ); if ( ( ! $slug_provided || $name_match->slug === $slug ) && in_array( $name, $sibling_names, true ) ) { $existing_term = $name_match; } elseif ( $slug_match && in_array( $slug, $sibling_slugs, true ) ) { $existing_term = $slug_match; } if ( $existing_term ) { return new WP_Error( 'term_exists', __( 'A term with the name provided already exists with this parent.' ), $existing_term->term_id ); } } else { return new WP_Error( 'term_exists', __( 'A term with the name provided already exists in this taxonomy.' ), $name_match->term_id ); } } } $slug = wp_unique_term_slug( $slug, (object) $args ); $data = compact( 'name', 'slug', 'term_group' ); /** * Filters term data before it is inserted into the database. * * @since 4.7.0 * * @param array $data Term data to be inserted. * @param string $taxonomy Taxonomy slug. * @param array $args Arguments passed to wp_insert_term(). */ $data = apply_filters( 'wp_insert_term_data', $data, $taxonomy, $args ); if ( false === $wpdb->insert( $wpdb->terms, $data ) ) { return new WP_Error( 'db_insert_error', __( 'Could not insert term into the database.' ), $wpdb->last_error ); } $term_id = (int) $wpdb->insert_id; // Seems unreachable. However, is used in the case that a term name is provided, which sanitizes to an empty string. if ( empty( $slug ) ) { $slug = sanitize_title( $slug, $term_id ); /** This action is documented in wp-includes/taxonomy.php */ do_action( 'edit_terms', $term_id, $taxonomy ); $wpdb->update( $wpdb->terms, compact( 'slug' ), compact( 'term_id' ) ); /** This action is documented in wp-includes/taxonomy.php */ do_action( 'edited_terms', $term_id, $taxonomy ); } $tt_id = $wpdb->get_var( $wpdb->prepare( "SELECT tt.term_taxonomy_id FROM $wpdb->term_taxonomy AS tt INNER JOIN $wpdb->terms AS t ON tt.term_id = t.term_id WHERE tt.taxonomy = %s AND t.term_id = %d", $taxonomy, $term_id ) ); if ( ! empty( $tt_id ) ) { return array( 'term_id' => $term_id, 'term_taxonomy_id' => $tt_id, ); } if ( false === $wpdb->insert( $wpdb->term_taxonomy, compact( 'term_id', 'taxonomy', 'description', 'parent' ) + array( 'count' => 0 ) ) ) { return new WP_Error( 'db_insert_error', __( 'Could not insert term taxonomy into the database.' ), $wpdb->last_error ); } $tt_id = (int) $wpdb->insert_id; /* * Sanity check: if we just created a term with the same parent + taxonomy + slug but a higher term_id than * an existing term, then we have unwittingly created a duplicate term. Delete the dupe, and use the term_id * and term_taxonomy_id of the older term instead. Then return out of the function so that the "create" hooks * are not fired. */ $duplicate_term = $wpdb->get_row( $wpdb->prepare( "SELECT t.term_id, t.slug, tt.term_taxonomy_id, tt.taxonomy FROM $wpdb->terms AS t INNER JOIN $wpdb->term_taxonomy AS tt ON ( tt.term_id = t.term_id ) WHERE t.slug = %s AND tt.parent = %d AND tt.taxonomy = %s AND t.term_id < %d AND tt.term_taxonomy_id != %d", $slug, $parent, $taxonomy, $term_id, $tt_id ) ); /** * Filters the duplicate term check that takes place during term creation. * * Term parent + taxonomy + slug combinations are meant to be unique, and wp_insert_term() * performs a last-minute confirmation of this uniqueness before allowing a new term * to be created. Plugins with different uniqueness requirements may use this filter * to bypass or modify the duplicate-term check. * * @since 5.1.0 * * @param object $duplicate_term Duplicate term row from terms table, if found. * @param string $term Term being inserted. * @param string $taxonomy Taxonomy name. * @param array $args Arguments passed to wp_insert_term(). * @param int $tt_id term_taxonomy_id for the newly created term. */ $duplicate_term = apply_filters( 'wp_insert_term_duplicate_term_check', $duplicate_term, $term, $taxonomy, $args, $tt_id ); if ( $duplicate_term ) { $wpdb->delete( $wpdb->terms, array( 'term_id' => $term_id ) ); $wpdb->delete( $wpdb->term_taxonomy, array( 'term_taxonomy_id' => $tt_id ) ); $term_id = (int) $duplicate_term->term_id; $tt_id = (int) $duplicate_term->term_taxonomy_id; clean_term_cache( $term_id, $taxonomy ); return array( 'term_id' => $term_id, 'term_taxonomy_id' => $tt_id, ); } /** * Fires immediately after a new term is created, before the term cache is cleaned. * * The {@see 'create_$taxonomy'} hook is also available for targeting a specific * taxonomy. * * @since 2.3.0 * @since 6.1.0 The `$args` parameter was added. * * @param int $term_id Term ID. * @param int $tt_id Term taxonomy ID. * @param string $taxonomy Taxonomy slug. * @param array $args Arguments passed to wp_insert_term(). */ do_action( 'create_term', $term_id, $tt_id, $taxonomy, $args ); /** * Fires after a new term is created for a specific taxonomy. * * The dynamic portion of the hook name, `$taxonomy`, refers * to the slug of the taxonomy the term was created for. * * Possible hook names include: * * - `create_category` * - `create_post_tag` * * @since 2.3.0 * @since 6.1.0 The `$args` parameter was added. * * @param int $term_id Term ID. * @param int $tt_id Term taxonomy ID. * @param array $args Arguments passed to wp_insert_term(). */ do_action( "create_{$taxonomy}", $term_id, $tt_id, $args ); /** * Filters the term ID after a new term is created. * * @since 2.3.0 * @since 6.1.0 The `$args` parameter was added. * * @param int $term_id Term ID. * @param int $tt_id Term taxonomy ID. * @param array $args Arguments passed to wp_insert_term(). */ $term_id = apply_filters( 'term_id_filter', $term_id, $tt_id, $args ); clean_term_cache( $term_id, $taxonomy ); /** * Fires after a new term is created, and after the term cache has been cleaned. * * The {@see 'created_$taxonomy'} hook is also available for targeting a specific * taxonomy. * * @since 2.3.0 * @since 6.1.0 The `$args` parameter was added. * * @param int $term_id Term ID. * @param int $tt_id Term taxonomy ID. * @param string $taxonomy Taxonomy slug. * @param array $args Arguments passed to wp_insert_term(). */ do_action( 'created_term', $term_id, $tt_id, $taxonomy, $args ); /** * Fires after a new term in a specific taxonomy is created, and after the term * cache has been cleaned. * * The dynamic portion of the hook name, `$taxonomy`, refers to the taxonomy slug. * * Possible hook names include: * * - `created_category` * - `created_post_tag` * * @since 2.3.0 * @since 6.1.0 The `$args` parameter was added. * * @param int $term_id Term ID. * @param int $tt_id Term taxonomy ID. * @param array $args Arguments passed to wp_insert_term(). */ do_action( "created_{$taxonomy}", $term_id, $tt_id, $args ); /** * Fires after a term has been saved, and the term cache has been cleared. * * The {@see 'saved_$taxonomy'} hook is also available for targeting a specific * taxonomy. * * @since 5.5.0 * @since 6.1.0 The `$args` parameter was added. * * @param int $term_id Term ID. * @param int $tt_id Term taxonomy ID. * @param string $taxonomy Taxonomy slug. * @param bool $update Whether this is an existing term being updated. * @param array $args Arguments passed to wp_insert_term(). */ do_action( 'saved_term', $term_id, $tt_id, $taxonomy, false, $args ); /** * Fires after a term in a specific taxonomy has been saved, and the term * cache has been cleared. * * The dynamic portion of the hook name, `$taxonomy`, refers to the taxonomy slug. * * Possible hook names include: * * - `saved_category` * - `saved_post_tag` * * @since 5.5.0 * @since 6.1.0 The `$args` parameter was added. * * @param int $term_id Term ID. * @param int $tt_id Term taxonomy ID. * @param bool $update Whether this is an existing term being updated. * @param array $args Arguments passed to wp_insert_term(). */ do_action( "saved_{$taxonomy}", $term_id, $tt_id, false, $args ); return array( 'term_id' => $term_id, 'term_taxonomy_id' => $tt_id, ); } /** * Creates term and taxonomy relationships. * * Relates an object (post, link, etc.) to a term and taxonomy type. Creates the * term and taxonomy relationship if it doesn't already exist. Creates a term if * it doesn't exist (using the slug). * * A relationship means that the term is grouped in or belongs to the taxonomy. * A term has no meaning until it is given context by defining which taxonomy it * exists under. * * @since 2.3.0 * * @global wpdb $wpdb WordPress database abstraction object. * * @param int $object_id The object to relate to. * @param string|int|array $terms A single term slug, single term ID, or array of either term slugs or IDs. * Will replace all existing related terms in this taxonomy. Passing an * empty value will remove all related terms. * @param string $taxonomy The context in which to relate the term to the object. * @param bool $append Optional. If false will delete difference of terms. Default false. * @return array|WP_Error Term taxonomy IDs of the affected terms or WP_Error on failure. */ function wp_set_object_terms( $object_id, $terms, $taxonomy, $append = false ) { global $wpdb; $object_id = (int) $object_id; if ( ! taxonomy_exists( $taxonomy ) ) { return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) ); } if ( ! is_array( $terms ) ) { $terms = array( $terms ); } if ( ! $append ) { $old_tt_ids = wp_get_object_terms( $object_id, $taxonomy, array( 'fields' => 'tt_ids', 'orderby' => 'none', 'update_term_meta_cache' => false, ) ); } else { $old_tt_ids = array(); } $tt_ids = array(); $term_ids = array(); $new_tt_ids = array(); foreach ( (array) $terms as $term ) { if ( '' === trim( $term ) ) { continue; } $term_info = term_exists( $term, $taxonomy ); if ( ! $term_info ) { // Skip if a non-existent term ID is passed. if ( is_int( $term ) ) { continue; } $term_info = wp_insert_term( $term, $taxonomy ); } if ( is_wp_error( $term_info ) ) { return $term_info; } $term_ids[] = $term_info['term_id']; $tt_id = $term_info['term_taxonomy_id']; $tt_ids[] = $tt_id; if ( $wpdb->get_var( $wpdb->prepare( "SELECT term_taxonomy_id FROM $wpdb->term_relationships WHERE object_id = %d AND term_taxonomy_id = %d", $object_id, $tt_id ) ) ) { continue; } /** * Fires immediately before an object-term relationship is added. * * @since 2.9.0 * @since 4.7.0 Added the `$taxonomy` parameter. * * @param int $object_id Object ID. * @param int $tt_id Term taxonomy ID. * @param string $taxonomy Taxonomy slug. */ do_action( 'add_term_relationship', $object_id, $tt_id, $taxonomy ); $wpdb->insert( $wpdb->term_relationships, array( 'object_id' => $object_id, 'term_taxonomy_id' => $tt_id, ) ); /** * Fires immediately after an object-term relationship is added. * * @since 2.9.0 * @since 4.7.0 Added the `$taxonomy` parameter. * * @param int $object_id Object ID. * @param int $tt_id Term taxonomy ID. * @param string $taxonomy Taxonomy slug. */ do_action( 'added_term_relationship', $object_id, $tt_id, $taxonomy ); $new_tt_ids[] = $tt_id; } if ( $new_tt_ids ) { wp_update_term_count( $new_tt_ids, $taxonomy ); } if ( ! $append ) { $delete_tt_ids = array_diff( $old_tt_ids, $tt_ids ); if ( $delete_tt_ids ) { $in_delete_tt_ids = "'" . implode( "', '", $delete_tt_ids ) . "'"; $delete_term_ids = $wpdb->get_col( $wpdb->prepare( "SELECT tt.term_id FROM $wpdb->term_taxonomy AS tt WHERE tt.taxonomy = %s AND tt.term_taxonomy_id IN ($in_delete_tt_ids)", $taxonomy ) ); $delete_term_ids = array_map( 'intval', $delete_term_ids ); $remove = wp_remove_object_terms( $object_id, $delete_term_ids, $taxonomy ); if ( is_wp_error( $remove ) ) { return $remove; } } } $t = get_taxonomy( $taxonomy ); if ( ! $append && isset( $t->sort ) && $t->sort ) { $values = array(); $term_order = 0; $final_tt_ids = wp_get_object_terms( $object_id, $taxonomy, array( 'fields' => 'tt_ids', 'update_term_meta_cache' => false, ) ); foreach ( $tt_ids as $tt_id ) { if ( in_array( (int) $tt_id, $final_tt_ids, true ) ) { $values[] = $wpdb->prepare( '(%d, %d, %d)', $object_id, $tt_id, ++$term_order ); } } if ( $values ) { if ( false === $wpdb->query( "INSERT INTO $wpdb->term_relationships (object_id, term_taxonomy_id, term_order) VALUES " . implode( ',', $values ) . ' ON DUPLICATE KEY UPDATE term_order = VALUES(term_order)' ) ) { return new WP_Error( 'db_insert_error', __( 'Could not insert term relationship into the database.' ), $wpdb->last_error ); } } } wp_cache_delete( $object_id, $taxonomy . '_relationships' ); wp_cache_delete( 'last_changed', 'terms' ); /** * Fires after an object's terms have been set. * * @since 2.8.0 * * @param int $object_id Object ID. * @param array $terms An array of object term IDs or slugs. * @param array $tt_ids An array of term taxonomy IDs. * @param string $taxonomy Taxonomy slug. * @param bool $append Whether to append new terms to the old terms. * @param array $old_tt_ids Old array of term taxonomy IDs. */ do_action( 'set_object_terms', $object_id, $terms, $tt_ids, $taxonomy, $append, $old_tt_ids ); return $tt_ids; } /** * Adds term(s) associated with a given object. * * @since 3.6.0 * * @param int $object_id The ID of the object to which the terms will be added. * @param string|int|array $terms The slug(s) or ID(s) of the term(s) to add. * @param array|string $taxonomy Taxonomy name. * @return array|WP_Error Term taxonomy IDs of the affected terms. */ function wp_add_object_terms( $object_id, $terms, $taxonomy ) { return wp_set_object_terms( $object_id, $terms, $taxonomy, true ); } /** * Removes term(s) associated with a given object. * * @since 3.6.0 * * @global wpdb $wpdb WordPress database abstraction object. * * @param int $object_id The ID of the object from which the terms will be removed. * @param string|int|array $terms The slug(s) or ID(s) of the term(s) to remove. * @param string $taxonomy Taxonomy name. * @return bool|WP_Error True on success, false or WP_Error on failure. */ function wp_remove_object_terms( $object_id, $terms, $taxonomy ) { global $wpdb; $object_id = (int) $object_id; if ( ! taxonomy_exists( $taxonomy ) ) { return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) ); } if ( ! is_array( $terms ) ) { $terms = array( $terms ); } $tt_ids = array(); foreach ( (array) $terms as $term ) { if ( '' === trim( $term ) ) { continue; } $term_info = term_exists( $term, $taxonomy ); if ( ! $term_info ) { // Skip if a non-existent term ID is passed. if ( is_int( $term ) ) { continue; } } if ( is_wp_error( $term_info ) ) { return $term_info; } $tt_ids[] = $term_info['term_taxonomy_id']; } if ( $tt_ids ) { $in_tt_ids = "'" . implode( "', '", $tt_ids ) . "'"; /** * Fires immediately before an object-term relationship is deleted. * * @since 2.9.0 * @since 4.7.0 Added the `$taxonomy` parameter. * * @param int $object_id Object ID. * @param array $tt_ids An array of term taxonomy IDs. * @param string $taxonomy Taxonomy slug. */ do_action( 'delete_term_relationships', $object_id, $tt_ids, $taxonomy ); $deleted = $wpdb->query( $wpdb->prepare( "DELETE FROM $wpdb->term_relationships WHERE object_id = %d AND term_taxonomy_id IN ($in_tt_ids)", $object_id ) ); wp_cache_delete( $object_id, $taxonomy . '_relationships' ); wp_cache_delete( 'last_changed', 'terms' ); /** * Fires immediately after an object-term relationship is deleted. * * @since 2.9.0 * @since 4.7.0 Added the `$taxonomy` parameter. * * @param int $object_id Object ID. * @param array $tt_ids An array of term taxonomy IDs. * @param string $taxonomy Taxonomy slug. */ do_action( 'deleted_term_relationships', $object_id, $tt_ids, $taxonomy ); wp_update_term_count( $tt_ids, $taxonomy ); return (bool) $deleted; } return false; } /** * Makes term slug unique, if it isn't already. * * The `$slug` has to be unique global to every taxonomy, meaning that one * taxonomy term can't have a matching slug with another taxonomy term. Each * slug has to be globally unique for every taxonomy. * * The way this works is that if the taxonomy that the term belongs to is * hierarchical and has a parent, it will append that parent to the $slug. * * If that still doesn't return a unique slug, then it tries to append a number * until it finds a number that is truly unique. * * The only purpose for `$term` is for appending a parent, if one exists. * * @since 2.3.0 * * @global wpdb $wpdb WordPress database abstraction object. * * @param string $slug The string that will be tried for a unique slug. * @param object $term The term object that the `$slug` will belong to. * @return string Will return a true unique slug. */ function wp_unique_term_slug( $slug, $term ) { global $wpdb; $needs_suffix = true; $original_slug = $slug; // As of 4.1, duplicate slugs are allowed as long as they're in different taxonomies. if ( ! term_exists( $slug ) || get_option( 'db_version' ) >= 30133 && ! get_term_by( 'slug', $slug, $term->taxonomy ) ) { $needs_suffix = false; } /* * If the taxonomy supports hierarchy and the term has a parent, make the slug unique * by incorporating parent slugs. */ $parent_suffix = ''; if ( $needs_suffix && is_taxonomy_hierarchical( $term->taxonomy ) && ! empty( $term->parent ) ) { $the_parent = $term->parent; while ( ! empty( $the_parent ) ) { $parent_term = get_term( $the_parent, $term->taxonomy ); if ( is_wp_error( $parent_term ) || empty( $parent_term ) ) { break; } $parent_suffix .= '-' . $parent_term->slug; if ( ! term_exists( $slug . $parent_suffix ) ) { break; } if ( empty( $parent_term->parent ) ) { break; } $the_parent = $parent_term->parent; } } // If we didn't get a unique slug, try appending a number to make it unique. /** * Filters whether the proposed unique term slug is bad. * * @since 4.3.0 * * @param bool $needs_suffix Whether the slug needs to be made unique with a suffix. * @param string $slug The slug. * @param object $term Term object. */ if ( apply_filters( 'wp_unique_term_slug_is_bad_slug', $needs_suffix, $slug, $term ) ) { if ( $parent_suffix ) { $slug .= $parent_suffix; } if ( ! empty( $term->term_id ) ) { $query = $wpdb->prepare( "SELECT slug FROM $wpdb->terms WHERE slug = %s AND term_id != %d", $slug, $term->term_id ); } else { $query = $wpdb->prepare( "SELECT slug FROM $wpdb->terms WHERE slug = %s", $slug ); } if ( $wpdb->get_var( $query ) ) { // phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared $num = 2; do { $alt_slug = $slug . "-$num"; $num++; $slug_check = $wpdb->get_var( $wpdb->prepare( "SELECT slug FROM $wpdb->terms WHERE slug = %s", $alt_slug ) ); } while ( $slug_check ); $slug = $alt_slug; } } /** * Filters the unique term slug. * * @since 4.3.0 * * @param string $slug Unique term slug. * @param object $term Term object. * @param string $original_slug Slug originally passed to the function for testing. */ return apply_filters( 'wp_unique_term_slug', $slug, $term, $original_slug ); } /** * Updates term based on arguments provided. * * The `$args` will indiscriminately override all values with the same field name. * Care must be taken to not override important information need to update or * update will fail (or perhaps create a new term, neither would be acceptable). * * Defaults will set 'alias_of', 'description', 'parent', and 'slug' if not * defined in `$args` already. * * 'alias_of' will create a term group, if it doesn't already exist, and * update it for the `$term`. * * If the 'slug' argument in `$args` is missing, then the 'name' will be used. * If you set 'slug' and it isn't unique, then a WP_Error is returned. * If you don't pass any slug, then a unique one will be created. * * @since 2.3.0 * * @global wpdb $wpdb WordPress database abstraction object. * * @param int $term_id The ID of the term. * @param string $taxonomy The taxonomy of the term. * @param array $args { * Optional. Array of arguments for updating a term. * * @type string $alias_of Slug of the term to make this term an alias of. * Default empty string. Accepts a term slug. * @type string $description The term description. Default empty string. * @type int $parent The id of the parent term. Default 0. * @type string $slug The term slug to use. Default empty string. * } * @return array|WP_Error An array containing the `term_id` and `term_taxonomy_id`, * WP_Error otherwise. */ function wp_update_term( $term_id, $taxonomy, $args = array() ) { global $wpdb; if ( ! taxonomy_exists( $taxonomy ) ) { return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) ); } $term_id = (int) $term_id; // First, get all of the original args. $term = get_term( $term_id, $taxonomy ); if ( is_wp_error( $term ) ) { return $term; } if ( ! $term ) { return new WP_Error( 'invalid_term', __( 'Empty Term.' ) ); } $term = (array) $term->data; // Escape data pulled from DB. $term = wp_slash( $term ); // Merge old and new args with new args overwriting old ones. $args = array_merge( $term, $args ); $defaults = array( 'alias_of' => '', 'description' => '', 'parent' => 0, 'slug' => '', ); $args = wp_parse_args( $args, $defaults ); $args = sanitize_term( $args, $taxonomy, 'db' ); $parsed_args = $args; // expected_slashed ($name) $name = wp_unslash( $args['name'] ); $description = wp_unslash( $args['description'] ); $parsed_args['name'] = $name; $parsed_args['description'] = $description; if ( '' === trim( $name ) ) { return new WP_Error( 'empty_term_name', __( 'A name is required for this term.' ) ); } if ( (int) $parsed_args['parent'] > 0 && ! term_exists( (int) $parsed_args['parent'] ) ) { return new WP_Error( 'missing_parent', __( 'Parent term does not exist.' ) ); } $empty_slug = false; if ( empty( $args['slug'] ) ) { $empty_slug = true; $slug = sanitize_title( $name ); } else { $slug = $args['slug']; } $parsed_args['slug'] = $slug; $term_group = isset( $parsed_args['term_group'] ) ? $parsed_args['term_group'] : 0; if ( $args['alias_of'] ) { $alias = get_term_by( 'slug', $args['alias_of'], $taxonomy ); if ( ! empty( $alias->term_group ) ) { // The alias we want is already in a group, so let's use that one. $term_group = $alias->term_group; } elseif ( ! empty( $alias->term_id ) ) { /* * The alias is not in a group, so we create a new one * and add the alias to it. */ $term_group = $wpdb->get_var( "SELECT MAX(term_group) FROM $wpdb->terms" ) + 1; wp_update_term( $alias->term_id, $taxonomy, array( 'term_group' => $term_group, ) ); } $parsed_args['term_group'] = $term_group; } /** * Filters the term parent. * * Hook to this filter to see if it will cause a hierarchy loop. * * @since 3.1.0 * * @param int $parent_term ID of the parent term. * @param int $term_id Term ID. * @param string $taxonomy Taxonomy slug. * @param array $parsed_args An array of potentially altered update arguments for the given term. * @param array $args Arguments passed to wp_update_term(). */ $parent = (int) apply_filters( 'wp_update_term_parent', $args['parent'], $term_id, $taxonomy, $parsed_args, $args ); // Check for duplicate slug. $duplicate = get_term_by( 'slug', $slug, $taxonomy ); if ( $duplicate && $duplicate->term_id !== $term_id ) { // If an empty slug was passed or the parent changed, reset the slug to something unique. // Otherwise, bail. if ( $empty_slug || ( $parent !== (int) $te