Commit e3adda4829 for wordpress.org
commit e3adda4829a41ef85c79a66a7884b72e27161807
Author: westonruter <westonruter@git.wordpress.org>
Date: Fri Oct 16 20:14:53 2026 +0000
Widgets: Use booleans in Categories widget arguments.
The Categories widget passed `show_count` and `hierarchical` to `wp_list_categories()` and `wp_dropdown_categories()` as the numeric strings `'0'` and `'1'`, while both functions document these arguments as `bool|int`. They are now passed as booleans, matching what the Categories block already passes. Core only checks these values for truthiness, so output is unchanged; a callback on the `widget_categories_args` or `widget_categories_dropdown_args` filter that compares them strictly to `'1'` or `'0'` is the only code affected, which is noted in the filters' `@since` tags.
The arguments passed to those filters, along with the widget's display arguments and instance settings, are now documented as hashes so that static analysis can type them. The `count`, `hierarchical` and `dropdown` settings are documented as the `0` or `1` that `update()` stores, while `widget()` keeps reading them loosely for instances saved before WordPress 2.8, which stored booleans. A missing title in the submitted settings no longer triggers an undefined array key warning in `update()`, which can happen when REST API form data omits it.
Developed in https://github.com/WordPress/wordpress-develop/pull/8071.
Follow-up to r10809, r41685, r64331.
Props westonruter, marian1.
See #65817, #65860.
Fixes #62762.
Built from https://develop.svn.wordpress.org/trunk@64413
git-svn-id: http://core.svn.wordpress.org/trunk@63563 1a063a9b-81f0-0310-95a4-ce76da25c4cd
diff --git a/wp-includes/version.php b/wp-includes/version.php
index 20ac727d3a..7cb0f26107 100644
--- a/wp-includes/version.php
+++ b/wp-includes/version.php
@@ -16,7 +16,7 @@
*
* @global string $wp_version
*/
-$wp_version = '7.2-alpha-64412';
+$wp_version = '7.2-alpha-64413';
/**
* Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.
diff --git a/wp-includes/widgets/class-wp-widget-categories.php b/wp-includes/widgets/class-wp-widget-categories.php
index 6e4773e27e..e26d607c4d 100644
--- a/wp-includes/widgets/class-wp-widget-categories.php
+++ b/wp-includes/widgets/class-wp-widget-categories.php
@@ -38,9 +38,22 @@ class WP_Widget_Categories extends WP_Widget {
* @since 4.2.0 Creates a unique HTML ID for the `<select>` element
* if more than one instance is displayed on the page.
*
- * @param array $args Display arguments including 'before_title', 'after_title',
- * 'before_widget', and 'after_widget'.
- * @param array $instance Settings for the current Categories widget instance.
+ * @param array $args {
+ * Display arguments.
+ *
+ * @type string $before_widget HTML markup to prepend to each widget in the sidebar.
+ * @type string $after_widget HTML markup to append to each widget in the sidebar.
+ * @type string $before_title HTML markup to prepend to the widget title when displayed.
+ * @type string $after_title HTML markup to append to the widget title when displayed.
+ * }
+ * @param array $instance {
+ * Settings for the current Categories widget instance.
+ *
+ * @type string $title Widget title.
+ * @type 0|1 $count Whether to show post counts.
+ * @type 0|1 $hierarchical Whether to show the category hierarchy.
+ * @type 0|1 $dropdown Whether to display the categories as a drop-down.
+ * }
*/
public function widget( $args, $instance ) {
static $first_dropdown = true;
@@ -51,9 +64,15 @@ class WP_Widget_Categories extends WP_Widget {
/** This filter is documented in wp-includes/widgets/class-wp-widget-pages.php */
$title = apply_filters( 'widget_title', $title, $instance, $this->id_base );
- $count = ! empty( $instance['count'] ) ? '1' : '0';
- $hierarchical = ! empty( $instance['hierarchical'] ) ? '1' : '0';
- $dropdown = ! empty( $instance['dropdown'] ) ? '1' : '0';
+ /*
+ * Although update() stores these flags as 0 or 1, they are checked loosely for back-compat:
+ * the keys are absent for an instance that has not been saved yet, instances saved before
+ * WordPress 2.8 stored booleans, and the_widget() passes along whatever values its caller
+ * supplies.
+ */
+ $count = ! empty( $instance['count'] );
+ $hierarchical = ! empty( $instance['hierarchical'] );
+ $dropdown = ! empty( $instance['dropdown'] );
echo $args['before_widget'];
@@ -82,11 +101,29 @@ class WP_Widget_Categories extends WP_Widget {
*
* @since 2.8.0
* @since 4.9.0 Added the `$instance` parameter.
+ * @since 7.2.0 The `show_count` and `hierarchical` arguments in `$cat_args` are now booleans instead of the numeric strings '0' and '1'.
*
* @see wp_dropdown_categories()
*
- * @param array $cat_args An array of Categories widget drop-down arguments.
- * @param array $instance Array of settings for the current widget.
+ * @param array $cat_args {
+ * An array of Categories widget drop-down arguments. See {@see wp_dropdown_categories()} for
+ * information on additional accepted arguments.
+ *
+ * @type string $orderby Which column to use for ordering categories. See {@see get_terms()}
+ * for a list of accepted values. Default 'name'.
+ * @type bool $show_count Whether to include post counts.
+ * @type bool $hierarchical Whether to traverse the taxonomy hierarchy.
+ * @type string $show_option_none Text to display for showing no categories. Set to 'Select Category'.
+ * @type string $id Value for the 'id' attribute of the select element.
+ * }
+ * @param array $instance {
+ * Array of settings for the current widget.
+ *
+ * @type string $title Widget title.
+ * @type 0|1 $count Whether to show post counts.
+ * @type 0|1 $hierarchical Whether to show the category hierarchy.
+ * @type 0|1 $dropdown Whether to display the categories as a drop-down.
+ * }
*/
wp_dropdown_categories( apply_filters( 'widget_categories_dropdown_args', $cat_args, $instance ) );
@@ -149,9 +186,26 @@ class WP_Widget_Categories extends WP_Widget {
*
* @since 2.8.0
* @since 4.9.0 Added the `$instance` parameter.
+ * @since 7.2.0 The `show_count` and `hierarchical` arguments in `$cat_args` are now booleans instead of the numeric strings '0' and '1'.
+ *
+ * @param array $cat_args {
+ * An array of Categories widget options. See {@see wp_list_categories()} for information on
+ * additional accepted arguments.
*
- * @param array $cat_args An array of Categories widget options.
- * @param array $instance Array of settings for the current widget.
+ * @type string $orderby Which column to use for ordering categories. See {@see get_terms()}
+ * for a list of accepted values. Default 'name'.
+ * @type bool $show_count Whether to include post counts.
+ * @type bool $hierarchical Whether to traverse the taxonomy hierarchy.
+ * @type string $title_li Text to use for the list title `<li>` element. Default empty string.
+ * }
+ * @param array $instance {
+ * Array of settings for the current widget.
+ *
+ * @type string $title Widget title.
+ * @type 0|1 $count Whether to show post counts.
+ * @type 0|1 $hierarchical Whether to show the category hierarchy.
+ * @type 0|1 $dropdown Whether to display the categories as a drop-down.
+ * }
*/
wp_list_categories( apply_filters( 'widget_categories_args', $cat_args, $instance ) );
?>
@@ -171,14 +225,36 @@ class WP_Widget_Categories extends WP_Widget {
*
* @since 2.8.0
*
- * @param array $new_instance New settings for this instance as input by the user via
- * WP_Widget::form().
- * @param array $old_instance Old settings for this instance.
- * @return array Updated settings to save.
+ * @param array $new_instance {
+ * New settings for this instance as input by the user via {@see WP_Widget::form()}. A checkbox
+ * submits 'on' when checked and is omitted when unchecked. A saved instance resubmitted
+ * through the REST API passes 0 or 1 instead.
+ *
+ * @type string $title Widget title.
+ * @type 'on'|0|1 $count Whether to show post counts.
+ * @type 'on'|0|1 $hierarchical Whether to show the category hierarchy.
+ * @type 'on'|0|1 $dropdown Whether to display the categories as a drop-down.
+ * }
+ * @param array $old_instance {
+ * Old settings for this instance.
+ *
+ * @type string $title Widget title.
+ * @type 0|1 $count Whether to show post counts.
+ * @type 0|1 $hierarchical Whether to show the category hierarchy.
+ * @type 0|1 $dropdown Whether to display the categories as a drop-down.
+ * }
+ * @return array {
+ * Updated settings to save.
+ *
+ * @type string $title Widget title.
+ * @type 0|1 $count Whether to show post counts.
+ * @type 0|1 $hierarchical Whether to show the category hierarchy.
+ * @type 0|1 $dropdown Whether to display the categories as a drop-down.
+ * }
*/
public function update( $new_instance, $old_instance ) {
$instance = $old_instance;
- $instance['title'] = sanitize_text_field( $new_instance['title'] );
+ $instance['title'] = sanitize_text_field( $new_instance['title'] ?? '' );
$instance['count'] = ! empty( $new_instance['count'] ) ? 1 : 0;
$instance['hierarchical'] = ! empty( $new_instance['hierarchical'] ) ? 1 : 0;
$instance['dropdown'] = ! empty( $new_instance['dropdown'] ) ? 1 : 0;
@@ -191,7 +267,14 @@ class WP_Widget_Categories extends WP_Widget {
*
* @since 2.8.0
*
- * @param array $instance Current settings.
+ * @param array $instance {
+ * Current settings.
+ *
+ * @type string $title Widget title.
+ * @type 0|1 $count Whether to show post counts.
+ * @type 0|1 $hierarchical Whether to show the category hierarchy.
+ * @type 0|1 $dropdown Whether to display the categories as a drop-down.
+ * }
*/
public function form( $instance ) {
// Defaults.