enmi-conf.org: comparison wp/wp-includes/taxonomy.php

equal deleted inserted replaced

-:34716fd837a4
+:be944660c56a
 				'add_new_item'               => __( 'Add New Link Category' ),
 				'new_item_name'              => __( 'New Link Category Name' ),
 				'separate_items_with_commas' => null,
 				'add_or_remove_items'        => null,
 				'choose_from_most_used'      => null,
-				'back_to_items'              => __( '&larr; Back to Link Categories' ),
+				'back_to_items'              => __( '&larr; Go to Link Categories' ),
 			),
 			'capabilities' => array(
 				'manage_terms' => 'manage_links',
 				'edit_terms'   => 'manage_links',
 				'delete_terms' => 'manage_links',
 			'show_ui'           => false,
 			'_builtin'          => true,
 			'show_in_nav_menus' => current_theme_supports( 'post-formats' ),
 		)
 	);
+	register_taxonomy(
+		'wp_theme',
+		array( 'wp_template' ),
+		array(
+			'public'            => false,
+			'hierarchical'      => false,
+			'labels'            => array(
+				'name'          => __( 'Themes' ),
+				'singular_name' => __( 'Theme' ),
+			),
+			'query_var'         => false,
+			'rewrite'           => false,
+			'show_ui'           => false,
+			'_builtin'          => true,
+			'show_in_nav_menus' => false,
+			'show_in_rest'      => false,
+		)
+	);
 }
 /**
 * Retrieves a list of registered taxonomy names or objects.
 *
 * @param string       $taxonomy    Taxonomy key, must not exceed 32 characters.
 * @param array|string $object_type Object type or array of object types with which the taxonomy should be associated.
 * @param array|string $args        {
 *     Optional. Array or query string of arguments for registering a taxonomy.
 *
-*     @type array         $labels                An array of labels for this taxonomy. By default, Tag labels are
+*     @type string[]      $labels                An array of labels for this taxonomy. By default, Tag labels are
 *                                                used for non-hierarchical taxonomies, and Category labels are used
 *                                                for hierarchical taxonomies. See accepted values in
 *                                                get_taxonomy_labels(). Default empty array.
 *     @type string        $description           A short descriptive summary of what the taxonomy is for. Default empty.
 *     @type bool          $public                Whether a taxonomy is intended for use publicly either via
 *                                                post_tags_meta_box() is used for non-hierarchical. If false, no meta
 *                                                box is shown.
 *     @type callable      $meta_box_sanitize_cb  Callback function for sanitizing taxonomy data saved from a meta
 *                                                box. If no callback is defined, an appropriate one is determined
 *                                                based on the value of `$meta_box_cb`.
-*     @type array         $capabilities {
+*     @type string[]      $capabilities {
 *         Array of capabilities for this taxonomy.
 *
 *         @type string $manage_terms Default 'manage_categories'.
 *         @type string $edit_terms   Default 'manage_categories'.
 *         @type string $delete_terms Default 'manage_categories'.
 *
 *         @type string $name         Name of default term.
 *         @type string $slug         Slug for default term. Default empty.
 *         @type string $description  Description for default term. Default empty.
 *     }
+*     @type bool          $sort                  Whether terms in this taxonomy should be sorted in the order they are
+*                                                provided to `wp_set_object_terms()`. Default null which equates to false.
+*     @type array         $args                  Array of arguments to automatically use inside `wp_get_object_terms()`
+*                                                for this taxonomy.
 *     @type bool          $_builtin              This taxonomy is a "built-in" taxonomy. INTERNAL USE ONLY!
 *                                                Default false.
 * }
 * @return WP_Taxonomy|WP_Error The registered taxonomy object on success, WP_Error object on failure.
 */
 *
 * @global WP    $wp            Current WordPress environment instance.
 * @global array $wp_taxonomies List of taxonomies.
 *
 * @param string $taxonomy Taxonomy name.
-* @return bool|WP_Error True on success, WP_Error on failure or if the taxonomy doesn't exist.
+* @return true|WP_Error True on success, WP_Error on failure or if the taxonomy doesn't exist.
 */
 function unregister_taxonomy( $taxonomy ) {
 	if ( ! taxonomy_exists( $taxonomy ) ) {
 		return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) );
 	}
 *
 * @since 3.0.0
 * @since 4.3.0 Added the `no_terms` label.
 * @since 4.4.0 Added the `items_list_navigation` and `items_list` labels.
 * @since 4.9.0 Added the `most_used` and `back_to_items` labels.
+* @since 5.7.0 Added the `filter_by_item` label.
+* @since 5.8.0 Added the `item_link` and `item_link_description` labels.
 *
 * @param WP_Taxonomy $tax Taxonomy object.
 * @return object {
 *     Taxonomy labels object. The first default value is for non-hierarchical taxonomies
 *     (like tags) and the second one is for hierarchical taxonomies (like categories).
 *                                              'Choose from the most used tags', used in the meta box.
 *     @type string $not_found                  Default 'No tags found'/'No categories found', used in
 *                                              the meta box and taxonomy list table.
 *     @type string $no_terms                   Default 'No tags'/'No categories', used in the posts and media
 *                                              list tables.
+*     @type string $filter_by_item             This label is only used for hierarchical taxonomies. Default
+*                                              'Filter by category', used in the posts list table.
 *     @type string $items_list_navigation      Label for the table pagination hidden heading.
 *     @type string $items_list                 Label for the table hidden heading.
 *     @type string $most_used                  Title for the Most Used tab. Default 'Most Used'.
 *     @type string $back_to_items              Label displayed after a term has been updated.
+*     @type string $item_link                  Used in the block editor. Title for a navigation link block variation.
+*                                              Default 'Tag Link'/'Category Link'.
+*     @type string $item_link_description      Used in the block editor. Description for a navigation link block
+*                                              variation. Default 'A link to a tag'/'A link to a category'.
 * }
 */
 function get_taxonomy_labels( $tax ) {
 	$tax->labels = (array) $tax->labels;
 		'separate_items_with_commas' => array( __( 'Separate tags with commas' ), null ),
 		'add_or_remove_items'        => array( __( 'Add or remove tags' ), null ),
 		'choose_from_most_used'      => array( __( 'Choose from the most used tags' ), null ),
 		'not_found'                  => array( __( 'No tags found.' ), __( 'No categories found.' ) ),
 		'no_terms'                   => array( __( 'No tags' ), __( 'No categories' ) ),
+		'filter_by_item'             => array( null, __( 'Filter by category' ) ),
 		'items_list_navigation'      => array( __( 'Tags list navigation' ), __( 'Categories list navigation' ) ),
 		'items_list'                 => array( __( 'Tags list' ), __( 'Categories list' ) ),
 		/* translators: Tab heading when selecting from the most used terms. */
 		'most_used'                  => array( _x( 'Most Used', 'tags' ), _x( 'Most Used', 'categories' ) ),
-		'back_to_items'              => array( __( '&larr; Back to Tags' ), __( '&larr; Back to Categories' ) ),
+		'back_to_items'              => array( __( '&larr; Go to Tags' ), __( '&larr; Go to Categories' ) ),
+		'item_link'                  => array(
+			_x( 'Tag Link', 'navigation link block title' ),
+			_x( 'Category Link', 'navigation link block description' ),
+		),
+		'item_link_description'      => array(
+			_x( 'A link to a tag.', 'navigation link block description' ),
+			_x( 'A link to a category.', 'navigation link block description' ),
+		),
 	);
 	$nohier_vs_hier_defaults['menu_name'] = $nohier_vs_hier_defaults['name'];
 	$labels = _get_custom_object_labels( $tax, $nohier_vs_hier_defaults );
 	$taxonomy = $tax->name;
 	/**
 	 * Filters the labels of a specific taxonomy.
 	 *
 	 * The dynamic portion of the hook name, `$taxonomy`, refers to the taxonomy slug.
+	 *
+	 * Possible hook names include:
+	 *
+	 *  - `taxonomy_labels_category`
+	 *  - `taxonomy_labels_post_tag`
 	 *
 	 * @since 4.4.0
 	 *
 	 * @see get_taxonomy_labels() for the full list of taxonomy labels.
 	 *
 //
 /**
 * Retrieve object_ids of valid taxonomy and term.
 *
-* The strings of $taxonomies must exist before this function will continue. On
+* The strings of $taxonomies must exist before this function will continue.
-* failure of finding a valid taxonomy, it will return an WP_Error class, kind
+* On failure of finding a valid taxonomy, it will return a WP_Error class,
-* of like Exceptions in PHP 5, except you can't catch them. Even so, you can
+* kind of like Exceptions in PHP 5, except you can't catch them. Even so,
-* still test for the WP_Error class and get the error message.
+* you can still test for the WP_Error class and get the error message.
 *
 * The $terms aren't checked the same as $taxonomies, but still need to exist
 * for $object_ids to be returned.
 *
 * It is possible to change the order that object_ids is returned by either
 * @global wpdb $wpdb WordPress database abstraction object.
 *
 * @param int|array    $term_ids   Term ID or array of term IDs of terms that will be used.
 * @param string|array $taxonomies String of taxonomy name or Array of string values of taxonomy names.
 * @param array|string $args       Change the order of the object_ids, either ASC or DESC.
-* @return WP_Error|array If the taxonomy does not exist, then WP_Error will be returned. On success.
+* @return array|WP_Error An array of $object_ids on success, WP_Error if the taxonomy does not exist.
-*  the array can be empty meaning that there are no $object_ids found or it will return the $object_ids found.
 */
 function get_objects_in_term( $term_ids, $taxonomies, $args = array() ) {
 	global $wpdb;
 	if ( ! is_array( $term_ids ) ) {
 	// Ensure for filters that this is not empty.
 	$taxonomy = $_term->taxonomy;
 	/**
 	 * Filters a taxonomy term object.
+	 *
+	 * The {@see 'get_$taxonomy'} hook is also available for targeting a specific
+	 * taxonomy.
 	 *
 	 * @since 2.3.0
 	 * @since 4.4.0 `$_term` is now a `WP_Term` object.
 	 *
 	 * @param WP_Term $_term    Term object.
 function get_term_children( $term_id, $taxonomy ) {
 	if ( ! taxonomy_exists( $taxonomy ) ) {
 		return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) );
 	}
-	$term_id = intval( $term_id );
+	$term_id = (int) $term_id;
 	$terms = _get_term_hierarchy( $taxonomy );
 	if ( ! isset( $terms[ $term_id ] ) ) {
 		return array();
 	return sanitize_term( $term, $taxonomy, 'edit' );
 }
 /**
-* Retrieve the terms in a given taxonomy or list of taxonomies.
+* Retrieves the terms in a given taxonomy or list of taxonomies.
 *
 * You can fully inject any customizations to the query before it is sent, as
 * well as control the output with a filter.
+*
+* The return type varies depending on the value passed to `$args['fields']`. See
+* WP_Term_Query::get_terms() for details. In all cases, a `WP_Error` object will
+* be returned if an invalid taxonomy is requested.
 *
 * The {@see 'get_terms'} filter will be called when the cache has the term and will
 * pass the found term along with the array of $taxonomies and array of $args.
 * This filter is also called before the array of terms is passed and will pass
 * the array of terms, along with the $taxonomies and $args.
 * @since 4.8.0 Introduced 'suppress_filter' 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.
+*                                 for information on accepted arguments. Default empty array.
-* @param array|string $deprecated Argument array, when using the legacy function parameter format. If present,
+* @param array|string $deprecated Optional. Argument array, when using the legacy function parameter format.
-*                                 this parameter will be interpreted as `$args`, and the first function parameter
+*                                 If present, this parameter will be interpreted as `$args`, and the first
-*                                 will be parsed as a taxonomy or array of taxonomies.
+*                                 function parameter will be parsed as a taxonomy or array of taxonomies.
-* @return WP_Term[]|int|WP_Error Array of WP_Term instances, a count thereof,
+*                                 Default empty.
-*                                or WP_Error if any of the taxonomies do not exist.
+* @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 the function description for more information.
 */
 function get_terms( $args = array(), $deprecated = '' ) {
 	$term_query = new WP_Term_Query();
 	$defaults = array(
 *
 * @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.
+*                        This parameter has no effect if `$key` is not specified.
 *                        Default false.
-* @return mixed An array if $single is false. The value of the meta field
+* @return mixed An array of values if `$single` is false.
-*               if $single is true. False for an invalid $term_id.
+*               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 );
 }
 	return term_is_ancestor_of( $term1, get_term( $term2->parent, $taxonomy ), $taxonomy );
 }
 /**
-* Sanitize Term all fields.
+* Sanitize all term fields.
 *
 * Relies on sanitize_term_field() to sanitize the term. The difference is that
-* this function will sanitize <strong>all</strong> fields. The context is based
+* 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.
+* 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 'edit', 'db',
+* @param string       $context  Optional. Context in which to sanitize the term.
-*                               'display', 'attribute', or 'js'. Default 'display'.
+*                               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' );
 *
 * @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 'edit', 'db', 'display',
+* @param string $context  Context in which to sanitize the term field.
-*                         'attribute', or 'js'.
+*                         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 ) ) {
 	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;
 }
 /**
 * Count 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.
-* @param string       $taxonomy Taxonomy name.
+*
-* @param array|string $args     Optional. Array of arguments that get passed to get_terms().
+* @internal The `$deprecated` parameter is parsed for backward compatibility only.
-*                               Default empty array.
+*
-* @return array|int|WP_Error Number of terms in that taxonomy or WP_Error if the taxonomy does not exist.
+* @param array|string $args       Optional. Array of arguments that get passed to get_terms().
-*/
+*                                 Default empty array.
-function wp_count_terms( $taxonomy, $args = array() ) {
+* @param array|string $deprecated Optional. Argument array, when using the legacy function parameter format.
-	$defaults = array(
+*                                 If present, this parameter will be interpreted as `$args`, and the first
-		'taxonomy'   => $taxonomy,
+*                                 function parameter will be parsed as a taxonomy or array of taxonomies.
-		'hide_empty' => false,
+*                                 Default empty.
-	);
+* @return string|WP_Error Numeric string containing the number of terms in that
-	$args     = wp_parse_args( $args, $defaults );
+*                         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'] );
 	$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.
 	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 mixed   $deleted_term Copy of the already-deleted term, in the form specified
+	 * @param WP_Term $deleted_term Copy of the already-deleted term.
-	 *                              by the parent function. WP_Error otherwise.
 	 * @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 mixed   $deleted_term Copy of the already-deleted term, in the form specified
+	 * @param WP_Term $deleted_term Copy of the already-deleted term.
-	 *                              by the parent function. WP_Error otherwise.
 	 * @param array   $object_ids   List of term object IDs.
 	 */
 	do_action( "delete_{$taxonomy}", $term, $tt_id, $deleted_term, $object_ids );
 	return true;
 * @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 array|WP_Error The requested term data or empty array if no terms found.
+* @return WP_Term[]|WP_Error Array of terms or empty array if no terms found.
-*                        WP_Error if any of the taxonomies don't exist.
+*                            WP_Error if any of the taxonomies don't exist.
 */
 function wp_get_object_terms( $object_ids, $taxonomies, $args = array() ) {
 	if ( empty( $object_ids ) || empty( $taxonomies ) ) {
 		return array();
 	}
 	$object_ids = array_map( 'intval', $object_ids );
 	$args = wp_parse_args( $args );
 	/**
-	 * Filter arguments for retrieving object terms.
+	 * 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.
 	/**
 	 * Filters the terms for a given object or objects.
 	 *
 	 * @since 4.2.0
 	 *
-	 * @param array    $terms      Array of terms for the given object or objects.
+	 * @param WP_Term[] $terms      Array of terms for the given object or objects.
-	 * @param int[]    $object_ids Array of object IDs for which terms were retrieved.
+	 * @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 string[]  $taxonomies Array of taxonomy names from which terms were retrieved.
-	 * @param array    $args       Array of arguments for retrieving terms for the given
+	 * @param array     $args       Array of arguments for retrieving terms for the given
-	 *                             object(s). See wp_get_object_terms() for details.
+	 *                              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 ) ) . "'";
 	 * 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 array    $terms      Array of terms for the given object or objects.
+	 * @param WP_Term[] $terms      Array of terms for the given object or objects.
-	 * @param int[]    $object_ids Array of object IDs for which terms were retrieved.
+	 * @param string    $object_ids Comma separated list of object IDs for which terms were retrieved.
-	 * @param string[] $taxonomies Array of taxonomy names from 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
+	 * @param array     $args       Array of arguments for retrieving terms for the given
-	 *                             object(s). See wp_get_object_terms() for details.
+	 *                              object(s). See wp_get_object_terms() for details.
 	 */
 	return apply_filters( 'wp_get_object_terms', $terms, $object_ids, $taxonomies, $args );
 }
 /**
 * @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 string of arguments for inserting a term.
+*     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 containing the `term_id` and `term_taxonomy_id`,
+* @return array|WP_Error {
-*                        WP_Error otherwise.
+*     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 ) ) {
 		'parent'      => 0,
 		'slug'        => '',
 	);
 	$args     = wp_parse_args( $args, $defaults );
-	if ( $args['parent'] > 0 && ! term_exists( (int) $args['parent'] ) ) {
+	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;
 	}
 	/**
 	 * 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
 	 *
 	 * @param int    $term_id  Term ID.
 	 * @param int    $tt_id    Term taxonomy ID.
 	 * @param string $taxonomy Taxonomy slug.
 	 * 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
 	 *
 	 * @param int $term_id Term ID.
 	 * @param int $tt_id   Term taxonomy ID.
 	 */
 	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
 	 *
 	 * @param int    $term_id  Term ID.
 	 * @param int    $tt_id    Term taxonomy ID.
 	 * 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
 	 *
 	 * @param int $term_id Term ID.
 	 * @param int $tt_id   Term taxonomy ID.
 	 */
 	do_action( "created_{$taxonomy}", $term_id, $tt_id );
 	/**
 	 * 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
 	 *
 	 * @param int    $term_id  Term ID.
 	 * @param int    $tt_id    Term taxonomy ID.
 	/**
 	 * 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
 	 *
 	 * @param int  $term_id Term ID.
 	 * @param int  $tt_id   Term taxonomy ID.
 				$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 " . join( ',', $values ) . ' ON DUPLICATE KEY UPDATE term_order = VALUES(term_order)' ) ) {
+			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 );
 			}
 		}
 	}
 	 * 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 terms.
+	 * @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.
 	 */
 	if ( '' === trim( $name ) ) {
 		return new WP_Error( 'empty_term_name', __( 'A name is required for this term.' ) );
 	}
-	if ( $parsed_args['parent'] > 0 && ! term_exists( (int) $parsed_args['parent'] ) ) {
+	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'] ) ) {
 		$slug = sanitize_title( $name, $term_id );
 		$wpdb->update( $wpdb->terms, compact( 'slug' ), compact( 'term_id' ) );
 	}
 	/**
-	 * Fires immediately after the given terms are edited.
+	 * Fires immediately after a term is updated in the database, but before its
+	 * term-taxonomy relationship is updated.
 	 *
 	 * @since 2.9.0
 	 *
 	 * @param int    $term_id  Term ID
 	 * @param string $taxonomy Taxonomy slug.
 	 */
 	do_action( 'edited_term_taxonomy', $tt_id, $taxonomy );
 	/**
 	 * Fires after a term has been updated, but before the term cache has been cleaned.
+	 *
+	 * The {@see 'edit_$taxonomy'} hook is also available for targeting a specific
+	 * taxonomy.
 	 *
 	 * @since 2.3.0
 	 *
 	 * @param int    $term_id  Term ID.
 	 * @param int    $tt_id    Term taxonomy ID.
 	 * Fires after a term in a specific taxonomy has been updated, but before the term
 	 * cache has been cleaned.
 	 *
 	 * The dynamic portion of the hook name, `$taxonomy`, refers to the taxonomy slug.
 	 *
+	 * Possible hook names include:
+	 *
+	 *  - `edit_category`
+	 *  - `edit_post_tag`
+	 *
 	 * @since 2.3.0
 	 *
 	 * @param int $term_id Term ID.
 	 * @param int $tt_id   Term taxonomy ID.
 	 */
 	clean_term_cache( $term_id, $taxonomy );
 	/**
 	 * Fires after a term has been updated, and the term cache has been cleaned.
+	 *
+	 * The {@see 'edited_$taxonomy'} hook is also available for targeting a specific
+	 * taxonomy.
 	 *
 	 * @since 2.3.0
 	 *
 	 * @param int    $term_id  Term ID.
 	 * @param int    $tt_id    Term taxonomy ID.
 	/**
 	 * Fires after a term for a specific taxonomy has been updated, and the term
 	 * cache has been cleaned.
 	 *
 	 * The dynamic portion of the hook name, `$taxonomy`, refers to the taxonomy slug.
+	 *
+	 * Possible hook names include:
+	 *
+	 *  - `edited_category`
+	 *  - `edited_post_tag`
 	 *
 	 * @since 2.3.0
 	 *
 	 * @param int $term_id Term ID.
 	 * @param int $tt_id   Term taxonomy ID.
 	// Backward compatibility for if a plugin is putting objects into the cache, rather than IDs.
 	$term_ids = array();
 	foreach ( $_term_ids as $term_id ) {
 		if ( is_numeric( $term_id ) ) {
-			$term_ids[] = intval( $term_id );
+			$term_ids[] = (int) $term_id;
 		} elseif ( isset( $term_id->term_id ) ) {
-			$term_ids[] = intval( $term_id->term_id );
+			$term_ids[] = (int) $term_id->term_id;
 		}
 	}
 	// Fill the term objects.
 	_prime_term_caches( $term_ids );
 *
 * @since 2.3.0
 *
 * @param string|int[]    $object_ids  Comma-separated list or array of term object IDs.
 * @param string|string[] $object_type The taxonomy object type or array of the same.
-* @return void|false False if all of the terms in `$object_ids` are already cached.
+* @return void|false Void on success or if the `$object_ids` parameter is empty,
+*                    false if all of the terms in `$object_ids` are already cached.
 */
 function update_object_term_cache( $object_ids, $object_type ) {
 	if ( empty( $object_ids ) ) {
 		return;
 	}
 * @access private
 * @since 2.3.0
 *
 * @global wpdb $wpdb WordPress database abstraction object.
 *
-* @param array  $terms    List of term objects (passed by reference).
+* @param object[]|WP_Term[] $terms    List of term objects (passed by reference).
-* @param string $taxonomy Term context.
+* @param string             $taxonomy Term context.
 */
 function _pad_term_counts( &$terms, $taxonomy ) {
 	global $wpdb;
 	// This function only works for hierarchical taxonomies like post categories.
 function _prime_term_caches( $term_ids, $update_meta_cache = true ) {
 	global $wpdb;
 	$non_cached_ids = _get_non_cached_ids( $term_ids, 'terms' );
 	if ( ! empty( $non_cached_ids ) ) {
-		$fresh_terms = $wpdb->get_results( sprintf( "SELECT t.*, tt.* FROM $wpdb->terms AS t INNER JOIN $wpdb->term_taxonomy AS tt ON t.term_id = tt.term_id WHERE t.term_id IN (%s)", join( ',', array_map( 'intval', $non_cached_ids ) ) ) );
+		$fresh_terms = $wpdb->get_results( sprintf( "SELECT t.*, tt.* FROM $wpdb->terms AS t INNER JOIN $wpdb->term_taxonomy AS tt ON t.term_id = tt.term_id WHERE t.term_id IN (%s)", implode( ',', array_map( 'intval', $non_cached_ids ) ) ) );
 		update_term_cache( $fresh_terms, $update_meta_cache );
 		if ( $update_meta_cache ) {
 			update_termmeta_cache( $non_cached_ids );
 	if ( $object_types ) {
 		$object_types = esc_sql( array_filter( $object_types, 'post_type_exists' ) );
 	}
+	$post_statuses = array( 'publish' );
+	/**
+	 * Filters the post statuses for updating the term count.
+	 *
+	 * @since 5.7.0
+	 *
+	 * @param string[]    $post_statuses List of post statuses to include in the count. Default is 'publish'.
+	 * @param WP_Taxonomy $taxonomy      Current taxonomy object.
+	 */
+	$post_statuses = esc_sql( apply_filters( 'update_post_term_count_statuses', $post_statuses, $taxonomy ) );
 	foreach ( (array) $terms as $term ) {
 		$count = 0;
 		// Attachments can be 'inherit' status, we need to base count off the parent's status if so.
 		if ( $check_attachments ) {
-			$count += (int) $wpdb->get_var( $wpdb->prepare( "SELECT COUNT(*) FROM $wpdb->term_relationships, $wpdb->posts p1 WHERE p1.ID = $wpdb->term_relationships.object_id AND ( post_status = 'publish' OR ( post_status = 'inherit' AND post_parent > 0 AND ( SELECT post_status FROM $wpdb->posts WHERE ID = p1.post_parent ) = 'publish' ) ) AND post_type = 'attachment' AND term_taxonomy_id = %d", $term ) );
+			// phpcs:ignore WordPress.DB.PreparedSQLPlaceholders.QuotedDynamicPlaceholderGeneration
+			$count += (int) $wpdb->get_var( $wpdb->prepare( "SELECT COUNT(*) FROM $wpdb->term_relationships, $wpdb->posts p1 WHERE p1.ID = $wpdb->term_relationships.object_id AND ( post_status IN ('" . implode( "', '", $post_statuses ) . "') OR ( post_status = 'inherit' AND post_parent > 0 AND ( SELECT post_status FROM $wpdb->posts WHERE ID = p1.post_parent ) IN ('" . implode( "', '", $post_statuses ) . "') ) ) AND post_type = 'attachment' AND term_taxonomy_id = %d", $term ) );
 		}
 		if ( $object_types ) {
 			// phpcs:ignore WordPress.DB.PreparedSQLPlaceholders.QuotedDynamicPlaceholderGeneration
-			$count += (int) $wpdb->get_var( $wpdb->prepare( "SELECT COUNT(*) FROM $wpdb->term_relationships, $wpdb->posts WHERE $wpdb->posts.ID = $wpdb->term_relationships.object_id AND post_status = 'publish' AND post_type IN ('" . implode( "', '", $object_types ) . "') AND term_taxonomy_id = %d", $term ) );
+			$count += (int) $wpdb->get_var( $wpdb->prepare( "SELECT COUNT(*) FROM $wpdb->term_relationships, $wpdb->posts WHERE $wpdb->posts.ID = $wpdb->term_relationships.object_id AND post_status IN ('" . implode( "', '", $post_statuses ) . "') AND post_type IN ('" . implode( "', '", $object_types ) . "') AND term_taxonomy_id = %d", $term ) );
 		}
 		/** This action is documented in wp-includes/taxonomy.php */
 		do_action( 'edit_term_taxonomy', $term, $taxonomy->name );
 		$wpdb->update( $wpdb->term_taxonomy, compact( 'count' ), array( 'term_taxonomy_id' => $term ) );
 function _split_shared_term( $term_id, $term_taxonomy_id, $record = true ) {
 	global $wpdb;
 	if ( is_object( $term_id ) ) {
 		$shared_term = $term_id;
-		$term_id     = intval( $shared_term->term_id );
+		$term_id     = (int) $shared_term->term_id;
 	}
 	if ( is_object( $term_taxonomy_id ) ) {
 		$term_taxonomy    = $term_taxonomy_id;
-		$term_taxonomy_id = intval( $term_taxonomy->term_taxonomy_id );
+		$term_taxonomy_id = (int) $term_taxonomy->term_taxonomy_id;
 	}
 	// If there are no shared term_taxonomy rows, there's nothing to do here.
 	$shared_tt_count = (int) $wpdb->get_var( $wpdb->prepare( "SELECT COUNT(*) FROM $wpdb->term_taxonomy tt WHERE tt.term_id = %d AND tt.term_taxonomy_id != %d", $term_id, $term_taxonomy_id ) );
 	wp_schedule_single_event( time() + ( 2 * MINUTE_IN_SECONDS ), 'wp_split_shared_term_batch' );
 	// Rekey shared term array for faster lookups.
 	$_shared_terms = array();
 	foreach ( $shared_terms as $shared_term ) {
-		$term_id                   = intval( $shared_term->term_id );
+		$term_id                   = (int) $shared_term->term_id;
 		$_shared_terms[ $term_id ] = $shared_term;
 	}
 	$shared_terms = $_shared_terms;
 	// Get term taxonomy data for all shared terms.
 	// Split term data recording is slow, so we do it just once, outside the loop.
 	$split_term_data    = get_option( '_split_terms', array() );
 	$skipped_first_term = array();
 	$taxonomies         = array();
 	foreach ( $shared_tts as $shared_tt ) {
-		$term_id = intval( $shared_tt->term_id );
+		$term_id = (int) $shared_tt->term_id;
 		// Don't split the first tt belonging to a given term_id.
 		if ( ! isset( $skipped_first_term[ $term_id ] ) ) {
 			$skipped_first_term[ $term_id ] = 1;
 			continue;
 	$taxonomy = $term->taxonomy;
 	$termlink = $wp_rewrite->get_extra_permastruct( $taxonomy );
 	/**
-	 * Filters the permalink structure for a terms before token replacement occurs.
+	 * Filters the permalink structure for a term before token replacement occurs.
 	 *
 	 * @since 4.9.0
 	 *
 	 * @param string  $termlink The permalink structure for the term's taxonomy.
 	 * @param WP_Term $term     The term object.
 		} else {
 			$termlink = "?taxonomy=$taxonomy&term=$slug";
 		}
 		$termlink = home_url( $termlink );
 	} else {
-		if ( $t->rewrite['hierarchical'] ) {
+		if ( ! empty( $t->rewrite['hierarchical'] ) ) {
 			$hierarchical_slugs = array();
 			$ancestors          = get_ancestors( $term->term_id, $taxonomy, 'taxonomy' );
 			foreach ( (array) $ancestors as $ancestor ) {
 				$ancestor_term        = get_term( $ancestor, $taxonomy );
 				$hierarchical_slugs[] = $ancestor_term->slug;
 		'after'  => '',
 	);
 	$parsed_args = wp_parse_args( $args, $defaults );
-	echo $parsed_args['before'] . join( $parsed_args['sep'], get_the_taxonomies( $parsed_args['post'], $parsed_args ) ) . $parsed_args['after'];
+	echo $parsed_args['before'] . implode( $parsed_args['sep'], get_the_taxonomies( $parsed_args['post'], $parsed_args ) ) . $parsed_args['after'];
 }
 /**
 * Retrieve all taxonomies associated with a post.
 *
 * Terms given as integers will only be checked against the object's terms' term_ids.
 * If no terms are given, determines if object is associated with any terms in the given taxonomy.
 *
 * @since 2.7.0
 *
-* @param int              $object_id ID of the object (post ID, link ID, ...).
+* @param int                       $object_id ID of the object (post ID, link ID, ...).
-* @param string           $taxonomy  Single taxonomy name.
+* @param string                    $taxonomy  Single taxonomy name.
-* @param int|string|array $terms     Optional. Term term_id, name, slug or array of said. Default null.
+* @param int|string|int[]|string[] $terms     Optional. Term ID, name, slug, or array of such
+*                                             to check against. Default null.
 * @return bool|WP_Error WP_Error on input error.
 */
 function is_object_in_term( $object_id, $taxonomy, $terms = null ) {
 	$object_id = (int) $object_id;
 	if ( ! $object_id ) {
 *
 * @since 3.1.0
 *
 * @param int    $term_id  Term ID.
 * @param string $taxonomy Taxonomy name.
-* @return int|false False on error.
+* @return int|false Parent term ID on success, false on failure.
 */
 function wp_get_term_taxonomy_parent_id( $term_id, $taxonomy ) {
 	$term = get_term( $term_id, $taxonomy );
 	if ( ! $term || is_wp_error( $term ) ) {
 		return false;

changeset 18	be944660c56a
parent 16	a86126ab1dd4
child 19	3d72ae0968f4