Ticket #25368: 25368.patch

src/wp-includes/widgets.php

@@ -859 +859 @@
 
         $sidebars_widgets = wp_get_sidebars_widgets();
         if ( empty( $wp_registered_sidebars[ $index ] ) || empty( $sidebars_widgets[ $index ] ) || ! is_array( $sidebars_widgets[ $index ] ) ) {
-                //temporary_hook #25368
-                do_action( 'temp_dynamic_sidebar_before', $index, false );
-                //temporary_hook #25368
-                do_action( 'temp_dynamic_sidebar_after',  $index, false );
-                //temporary_hook #25368
-                return apply_filters( 'temp_dynamic_sidebar_has_widgets', false, $index );
+                /** This action is documented in wp-includes/widgets.php */
+                do_action( 'dynamic_sidebar_before', $index, false );
+                /** This action is documented in wp-includes/widgets.php */
+                do_action( 'dynamic_sidebar_after',  $index, false );
+                /** This filter is documented in wp-includes/widgets.php */
+                return apply_filters( 'dynamic_sidebar_has_widgets', false, $index );
         }
 
-        //temporary_hook #25368
-        do_action( 'temp_dynamic_sidebar_before', $index, true );
+        /**
+         * Fires before widgets are rendered in a dynamic sidebar.
+         *
+         * Note: The action also fires for empty sidebars, and on both the front-end
+         * and back-end, including the Inactive Widgets sidebar on the Widgets screen.
+         *
+         * @since 3.9.0
+         *
+         * @param int|string $index       Index, name, or ID of the dynamic sidebar.
+         * @param bool       $has_widgets Whether the sidebar is populated with widgets.
+         *                                Default true.
+         */
+        do_action( 'dynamic_sidebar_before', $index, true );
         $sidebar = $wp_registered_sidebars[$index];
 
         $did_one = false;
@@ -892 +903 @@
                 $classname_ = ltrim($classname_, '_');
                 $params[0]['before_widget'] = sprintf($params[0]['before_widget'], $id, $classname_);
 
+                /**
+                 * Filter the parameters passed to a widget's display callback.
+                 *
+                 * Note: The filter is evaluated on both the front-end and back-end,
+                 * including for the Inactive Widgets sidebar on the Widgets screen.
+                 *
+                 * @since 2.5.0
+                 *
+                 * @see register_sidebar()
+                 *
+                 * @param array $params {
+                 *     @type array $args  {
+                 *         An array of widget display arguments.
+                 *
+                 *         @type string $name          Name of the sidebar the widget is assigned to.
+                 *         @type string $id            ID of the sidebar the widget is assigned to.
+                 *         @type string $description   The sidebar description.
+                 *         @type string $class         CSS class applied to the sidebar container.
+                 *         @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.
+                 *         @type string $widget_id     ID of the widget.
+                 *         @type string $widget_name   Name of the widget.
+                 *     }
+                 *     @type array $widget_args {
+                 *         An array of multi-widget arguments.
+                 *
+                 *         @type int $number Number increment used for multiples of the same widget.
+                 *     }
+                 * }
+                 */
                 $params = apply_filters( 'dynamic_sidebar_params', $params );
 
                 $callback = $wp_registered_widgets[$id]['callback'];
 
+                /**
+                 * Fires before a widget's display callback is called.
+                 *
+                 * Note: The action fires on both the front-end and back-end, including
+                 * for widgets in the Inactive Widgets sidebar on the Widgets screen.
+                 *
+                 * The action is not fired for empty sidebars.
+                 *
+                 * @since 3.0.0
+                 *
+                 * @param array $widget {
+                 *     An associative array of widget arguments.
+                 *
+                 *     @type string $name              Name of the widget.
+                 *     @type string $id                Widget ID.
+                 *     @type array|string $callback    When the hook is fired on the front-end, $callback is an array
+                 *                                     containing the widget object. Fired on the back-end, $callback
+                 *                                     is 'wp_widget_control', see $_callback.
+                 *     @type array        $params {
+                 *         An array of multi-widget arguments.
+                 *
+                 *         @type int $number Number increment used for multiples of the same widget.
+                 *     }
+                 *     @type string       $classname   CSS class applied to the widget container.
+                 *     @type string       $description The widget description.
+                 *     @type array        $_callback   When the hook is fired on the back-end, $_callback is populated
+                 *                                     with an array containing the widget object, see $callback.
+                 * }
+                 */
                 do_action( 'dynamic_sidebar', $wp_registered_widgets[$id] );
 
                 if ( is_callable($callback) ) {
@@ -904 +976 @@
                 }
         }
 
-        //temporary_hook #25368
-        do_action( 'temp_dynamic_sidebar_after', $index, true );
-        //temporary_hook #25368
-        $did_one = apply_filters( 'temp_dynamic_sidebar_has_widgets', $did_one, $index );
+        /**
+         * Fires after widgets are rendered in a dynamic sidebar.
+         *
+         * Note: The action also fires for empty sidebars, and on both the front-end
+         * and back-end, including the Inactive Widgets sidebar on the Widgets screen.
+         *
+         * @since 3.9.0
+         *
+         * @param int|string $index       Index, name, or ID of the dynamic sidebar.
+         * @param bool       $has_widgets Whether the sidebar is populated with widgets.
+         *                                Default true.
+         */
+        do_action( 'dynamic_sidebar_after', $index, true );
+
+        /**
+         * Filter whether a sidebar has widgets.
+         *
+         * Note: The filter is also evaluated for empty sidebars, and on both the front-end
+         * and back-end, including the Inactive Widgets sidebar on the Widgets screen.
+         *
+         * @since 3.9.0
+         *
+         * @param bool       $did_one Whether at least one widget was rendered in the sidebar.
+         *                            Default false.
+         * @param int|string $index   Index, name, or ID of the dynamic sidebar.
+         */
+
+        $did_one = apply_filters( 'dynamic_sidebar_has_widgets', $did_one, $index );
+
         return $did_one;
 }
 
@@ -987 +1084 @@
         $index = ( is_int($index) ) ? "sidebar-$index" : sanitize_title($index);
         $sidebars_widgets = wp_get_sidebars_widgets();
         $is_active_sidebar = ! empty( $sidebars_widgets[$index] );
-        //temporary_hook #25368
-        $is_active_sidebar = apply_filters( 'temp_is_active_sidebar', $is_active_sidebar, $index );
-        return $is_active_sidebar;
+
+        /**
+         * Filter whether a dynamic sidebar is considered "active".
+         *
+         * @since 3.9.0
+         *
+         * @param bool       $is_active_sidebar Whether or not the sidebar should be considered "active".
+         *                                      In other words, whether the sidebar contains any widgets.
+         * @param int|string $index             Index, name, or ID of the dynamic sidebar.
+         */
+        return apply_filters( 'is_active_sidebar', $is_active_sidebar, $index );
 }
 
 /* Internal Functions */