enmi-conf.org: comparison wp/wp-includes/category-template.php

equal deleted inserted replaced

-:7b1b88e27a20
+:48c4eec2b7e6
 	/**
 	 * Filters the array of categories to return for a post.
 	 *
 	 * @since 3.1.0
-	 * @since 4.4.0 Added `$post_id` parameter.
+	 * @since 4.4.0 Added the `$post_id` parameter.
 	 *
 	 * @param WP_Term[] $categories An array of categories to return for the post.
-	 * @param int|false $post_id    ID of the post.
+	 * @param int|false $post_id    The post ID.
 	 */
 	return apply_filters( 'get_the_categories', $categories, $post_id );
 }
 /**
 *
 * @global WP_Rewrite $wp_rewrite WordPress rewrite component.
 *
 * @param string $separator Optional. Separator between the categories. By default, the links are placed
 *                          in an unordered list. An empty string will result in the default behavior.
-* @param string $parents   Optional. How to display the parents.
+* @param string $parents   Optional. How to display the parents. Accepts 'multiple', 'single', or empty.
-* @param int    $post_id   Optional. Post ID to retrieve categories.
+*                          Default empty string.
+* @param int    $post_id   Optional. ID of the post to retrieve categories for. Defaults to the current post.
 * @return string Category list for a post.
 */
 function get_the_category_list( $separator = '', $parents = '', $post_id = false ) {
 	global $wp_rewrite;
 	 * Filters the categories before building the category list.
 	 *
 	 * @since 4.4.0
 	 *
 	 * @param WP_Term[] $categories An array of the post's categories.
-	 * @param int|bool  $post_id    ID of the post we're retrieving categories for.
+	 * @param int|false $post_id    ID of the post to retrieve categories for.
-	 *                              When `false`, we assume the current post in the loop.
+	 *                              When `false`, defaults to the current post in the loop.
 	 */
 	$categories = apply_filters( 'the_category_list', get_the_category( $post_id ), $post_id );
 	if ( empty( $categories ) ) {
 		/** This filter is documented in wp-includes/category-template.php */
 * @since 1.2.0
 * @since 2.7.0 The `$post` parameter was added.
 *
 * @param int|string|int[]|string[] $category Category ID, name, slug, or array of such
 *                                            to check against.
-* @param int|object                $post     Optional. Post to check instead of the current post.
+* @param int|WP_Post               $post     Optional. Post to check. Defaults to the current post.
 * @return bool True if the current post is in any of the given categories.
 */
 function in_category( $category, $post = null ) {
 	if ( empty( $category ) ) {
 		return false;
 *
 * @since 0.71
 *
 * @param string $separator Optional. Separator between the categories. By default, the links are placed
 *                          in an unordered list. An empty string will result in the default behavior.
-* @param string $parents   Optional. How to display the parents.
+* @param string $parents   Optional. How to display the parents. Accepts 'multiple', 'single', or empty.
-* @param int    $post_id   Optional. Post ID to retrieve categories.
+*                          Default empty string.
+* @param int    $post_id   Optional. ID of the post to retrieve categories for. Defaults to the current post.
 */
 function the_category( $separator = '', $parents = '', $post_id = false ) {
 	echo get_the_category_list( $separator, $parents, $post_id );
 }
 * the 'depth' argument.
 *
 * @since 2.1.0
 * @since 4.2.0 Introduced the `value_field` argument.
 * @since 4.6.0 Introduced the `required` argument.
+* @since 6.1.0 Introduced the `aria_describedby` argument.
 *
 * @param array|string $args {
 *     Optional. Array or string of arguments to generate a categories drop-down element. See WP_Term_Query::__construct()
 *     for information on additional accepted arguments.
 *
 *                                           Default false (create select element even if no categories are found).
 *     @type bool         $required          Whether the `<select>` element should have the HTML5 'required' attribute.
 *                                           Default false.
 *     @type Walker       $walker            Walker object to use to build the output. Default empty which results in a
 *                                           Walker_CategoryDropdown instance being used.
+*     @type string       $aria_describedby  The 'id' of an element that contains descriptive text for the select.
+*                                           Default empty string.
 * }
 * @return string HTML dropdown list of categories.
 */
 function wp_dropdown_categories( $args = '' ) {
 	$defaults = array(
 		'taxonomy'          => 'category',
 		'hide_if_empty'     => false,
 		'option_none_value' => -1,
 		'value_field'       => 'term_id',
 		'required'          => false,
+		'aria_describedby'  => '',
 	);
 	$defaults['selected'] = ( is_category() ) ? get_query_var( 'cat' ) : 0;
 	// Back compat.
 	$name     = esc_attr( $parsed_args['name'] );
 	$class    = esc_attr( $parsed_args['class'] );
 	$id       = $parsed_args['id'] ? esc_attr( $parsed_args['id'] ) : $name;
 	$required = $parsed_args['required'] ? 'required' : '';
+	$aria_describedby_attribute = $parsed_args['aria_describedby'] ? ' aria-describedby="' . esc_attr( $parsed_args['aria_describedby'] ) . '"' : '';
 	if ( ! $parsed_args['hide_if_empty'] || ! empty( $categories ) ) {
-		$output = "<select $required name='$name' id='$id' class='$class' $tab_index_attribute>\n";
+		$output = "<select $required name='$name' id='$id' class='$class'$tab_index_attribute$aria_describedby_attribute>\n";
 	} else {
 		$output = '';
 	}
 	if ( empty( $categories ) && ! $parsed_args['hide_if_empty'] && ! empty( $parsed_args['show_option_none'] ) ) {
 * Displays or retrieves the HTML list of categories.
 *
 * @since 2.1.0
 * @since 4.4.0 Introduced the `hide_title_if_empty` and `separator` arguments.
 * @since 4.4.0 The `current_category` argument was modified to optionally accept an array of values.
+* @since 6.1.0 Default value of the 'use_desc_for_title' argument was changed from 1 to 0.
 *
 * @param array|string $args {
 *     Array of optional arguments. See get_categories(), get_terms(), and WP_Term_Query::__construct()
 *     for information on additional accepted arguments.
 *
 *                                               categories will be output separated by `<br>` tags. Default 'list'.
 *     @type string       $taxonomy              Name of the taxonomy to retrieve. Default 'category'.
 *     @type string       $title_li              Text to use for the list title `<li>` element. Pass an empty string
 *                                               to disable. Default 'Categories'.
 *     @type bool|int     $use_desc_for_title    Whether to use the category description as the title attribute.
-*                                               Accepts 0, 1, or their bool equivalents. Default 1.
+*                                               Accepts 0, 1, or their bool equivalents. Default 0.
 *     @type Walker       $walker                Walker object to use to build the output. Default empty which results
 *                                               in a Walker_Category instance being used.
 * }
 * @return void|string|false Void if 'echo' argument is true, HTML list of categories if 'echo' is false.
 *                           False if the taxonomy does not exist.
 		'show_option_all'     => '',
 		'show_option_none'    => __( 'No categories' ),
 		'style'               => 'list',
 		'taxonomy'            => 'category',
 		'title_li'            => __( 'Categories' ),
-		'use_desc_for_title'  => 1,
+		'use_desc_for_title'  => 0,
 	);
 	$parsed_args = wp_parse_args( $args, $defaults );
 	if ( ! isset( $parsed_args['pad_counts'] ) && $parsed_args['show_count'] && $parsed_args['hierarchical'] ) {
 		$parsed_args['pad_counts'] = true;
 	}
 	// Descendants of exclusions should be excluded too.
-	if ( true == $parsed_args['hierarchical'] ) {
+	if ( $parsed_args['hierarchical'] ) {
 		$exclude_tree = array();
 		if ( $parsed_args['exclude_tree'] ) {
 			$exclude_tree = array_merge( $exclude_tree, wp_parse_id_list( $parsed_args['exclude_tree'] ) );
 		}
 *                                                can also affect how tags are sorted.
 *     @type string   $order                      How to order the tags. Accepts 'ASC' (ascending),
 *                                                'DESC' (descending), or 'RAND' (random). Default 'ASC'.
 *     @type int|bool $filter                     Whether to enable filtering of the final output
 *                                                via {@see 'wp_generate_tag_cloud'}. Default 1.
-*     @type string   $topic_count_text           Nooped plural text from _n_noop() to supply to
+*     @type array    $topic_count_text           Nooped plural text from _n_noop() to supply to
 *                                                tag counts. Default null.
 *     @type callable $topic_count_text_callback  Callback used to generate nooped plural text for
 *                                                tag counts based on the count. Default null.
 *     @type callable $topic_count_scale_callback Callback used to determine the tag count scaling
 *                                                value. Default default_topic_count_scale().
 		} else {
 			$translate_nooped_plural = false;
 		}
 	} elseif ( isset( $args['single_text'] ) && isset( $args['multiple_text'] ) ) {
 		// If no callback exists, look for the old-style single_text and multiple_text arguments.
-		// phpcs:ignore WordPress.WP.I18n.NonSingularStringLiteralSingle,WordPress.WP.I18n.NonSingularStringLiteralPlural
+		// phpcs:ignore WordPress.WP.I18n.NonSingularStringLiteralSingular,WordPress.WP.I18n.NonSingularStringLiteralPlural
 		$translate_nooped_plural = _n_noop( $args['single_text'], $args['multiple_text'] );
 	} else {
 		// This is the default for when no callback, plural, or argument is passed in.
 		/* translators: %s: Number of items (tags). */
 		$translate_nooped_plural = _n_noop( '%s item', '%s items' );
 * @since 3.1.0
 * @access private
 *
 * @param object $a The first object to compare.
 * @param object $b The second object to compare.
-* @return bool Whether the count value for `$a` is greater than the count value for `$b`.
+* @return int Negative number if `$a->count` is less than `$b->count`, zero if they are equal,
+*             or greater than zero if `$a->count` is greater than `$b->count`.
 */
 function _wp_object_count_sort_cb( $a, $b ) {
-	return ( $a->count > $b->count );
+	return ( $a->count - $b->count );
 }
 //
 // Helper functions.
 //
 * @return string
 */
 function walk_category_tree( ...$args ) {
 	// The user's options are the third parameter.
 	if ( empty( $args[2]['walker'] ) || ! ( $args[2]['walker'] instanceof Walker ) ) {
-		$walker = new Walker_Category;
+		$walker = new Walker_Category();
 	} else {
 		/**
 		 * @var Walker $walker
 		 */
 		$walker = $args[2]['walker'];
 * @return string
 */
 function walk_category_dropdown_tree( ...$args ) {
 	// The user's options are the third parameter.
 	if ( empty( $args[2]['walker'] ) || ! ( $args[2]['walker'] instanceof Walker ) ) {
-		$walker = new Walker_CategoryDropdown;
+		$walker = new Walker_CategoryDropdown();
 	} else {
 		/**
 		 * @var Walker $walker
 		 */
 		$walker = $args[2]['walker'];
 /**
 * Retrieves the tags for a post.
 *
 * @since 2.3.0
 *
-* @param int|WP_Post $post_id Post ID or object.
+* @param int|WP_Post $post Post ID or object.
 * @return WP_Term[]|false|WP_Error Array of WP_Term objects on success, false if there are no terms
 *                                  or the post does not exist, WP_Error on failure.
 */
-function get_the_tags( $post_id = 0 ) {
+function get_the_tags( $post = 0 ) {
-	$terms = get_the_terms( $post_id, 'post_tag' );
+	$terms = get_the_terms( $post, 'post_tag' );
 	/**
 	 * Filters the array of tags for the given post.
 	 *
 	 * @since 2.3.0
 * @return WP_Term[]|false|WP_Error Array of WP_Term objects on success, false if there are no terms
 *                                  or the post does not exist, WP_Error on failure.
 */
 function get_the_terms( $post, $taxonomy ) {
 	$post = get_post( $post );
 	if ( ! $post ) {
 		return false;
 	}
 	$terms = get_object_term_cache( $post->ID, $taxonomy );
 	if ( false === $terms ) {
 		$terms = wp_get_object_terms( $post->ID, $taxonomy );
 		if ( ! is_wp_error( $terms ) ) {
 			$term_ids = wp_list_pluck( $terms, 'term_id' );
 			wp_cache_add( $post->ID, $term_ids, $taxonomy . '_relationships' );
 *
 * @since 3.1.0
 *
 * @param string|int|array $category Optional. The category name/term_id/slug,
 *                                   or an array of them to check for. Default empty.
-* @param int|object       $post     Optional. Post to check instead of the current post.
+* @param int|WP_Post      $post     Optional. Post to check. Defaults to the current post.
 * @return bool True if the current post has any of the given categories
 *              (or any category, if no category specified). False otherwise.
 */
 function has_category( $category = '', $post = null ) {
 	return has_term( $category, 'category', $post );
 *              the post's tags' term_ids, not names or slugs.
 * @since 2.7.0 Can be used outside of the WordPress Loop if `$post` is provided.
 *
 * @param string|int|array $tag  Optional. The tag name/term_id/slug,
 *                               or an array of them to check for. Default empty.
-* @param int|object       $post Optional. Post to check instead of the current post.
+* @param int|WP_Post      $post Optional. Post to check. Defaults to the current post.
 * @return bool True if the current post has any of the given tags
 *              (or any tag, if no tag specified). False otherwise.
 */
 function has_tag( $tag = '', $post = null ) {
 	return has_term( $tag, 'post_tag', $post );
 * @since 3.1.0
 *
 * @param string|int|array $term     Optional. The term name/term_id/slug,
 *                                   or an array of them to check for. Default empty.
 * @param string           $taxonomy Optional. Taxonomy name. Default empty.
-* @param int|WP_Post      $post     Optional. Post to check instead of the current post.
+* @param int|WP_Post      $post     Optional. Post to check. Defaults to the current post.
 * @return bool True if the current post has any of the given terms
 *              (or any term, if no term specified). False otherwise.
 */
 function has_term( $term = '', $taxonomy = '', $post = null ) {
 	$post = get_post( $post );

changeset 21	48c4eec2b7e6
parent 19	3d72ae0968f4