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

equal deleted inserted replaced

-:be944660c56a
+:3d72ae0968f4
 * If theme support for 'widgets' has not yet been added when this function is
 * called, it will be automatically enabled through the use of add_theme_support()
 *
 * @since 2.2.0
 * @since 5.6.0 Added the `before_sidebar` and `after_sidebar` arguments.
+* @since 5.9.0 Added the `show_in_rest` argument.
 *
 * @global array $wp_registered_sidebars Registered sidebars.
 *
 * @param array|string $args {
 *     Optional. Array or string of arguments for the sidebar being registered.
 *                                  Outputs after the {@see 'dynamic_sidebar_before'} action.
 *                                  Default empty string.
 *     @type string $after_sidebar  HTML content to append to the sidebar when displayed.
 *                                  Outputs before the {@see 'dynamic_sidebar_after'} action.
 *                                  Default empty string.
+*     @type bool $show_in_rest     Whether to show this sidebar publicly in the REST API.
+*                                  Defaults to only showing the sidebar to administrator users.
 * }
 * @return string Sidebar ID added to $wp_registered_sidebars global.
 */
 function register_sidebar( $args = array() ) {
 	global $wp_registered_sidebars;
 		'after_widget'   => "</li>\n",
 		'before_title'   => '<h2 class="widgettitle">',
 		'after_title'    => "</h2>\n",
 		'before_sidebar' => '',
 		'after_sidebar'  => '',
+		'show_in_rest'   => false,
 	);
 	/**
 	 * Filters the sidebar default arguments.
 	 *
 	/**
 	 * Fires just before a widget is removed from a sidebar.
 	 *
 	 * @since 3.0.0
 	 *
-	 * @param int $id The widget ID.
+	 * @param int|string $id The widget ID.
 	 */
 	do_action( 'wp_unregister_sidebar_widget', $id );
 	wp_register_sidebar_widget( $id, '', '' );
 	wp_unregister_widget_control( $id );
 *
 *     @type int        $height  Never used. Default 200.
 *     @type int        $width   Width of the fully expanded control form (but try hard to use the default width).
 *                               Default 250.
 *     @type int|string $id_base Required for multi-widgets, i.e widgets that allow multiple instances such as the
-*                               text widget. The widget id will end up looking like `{$id_base}-{$unique_number}`.
+*                               text widget. The widget ID will end up looking like `{$id_base}-{$unique_number}`.
 * }
 * @param mixed      ...$params        Optional additional parameters to pass to the callback function when it's called.
 */
 function wp_register_widget_control( $id, $name, $control_callback, $options = array(), ...$params ) {
 	global $wp_registered_widget_controls, $wp_registered_widget_updates, $wp_registered_widgets, $_wp_deprecated_widgets_callbacks;
 	 */
 	return apply_filters( 'sidebars_widgets', $sidebars_widgets );
 }
 /**
+* Retrieves the registered sidebar with the given ID.
+*
+* @since 5.9.0
+*
+* @global array $wp_registered_sidebars The registered sidebars.
+*
+* @param string $id The sidebar ID.
+* @return array|null The discovered sidebar, or null if it is not registered.
+*/
+function wp_get_sidebar( $id ) {
+	global $wp_registered_sidebars;
+	foreach ( (array) $wp_registered_sidebars as $sidebar ) {
+		if ( $sidebar['id'] === $id ) {
+			return $sidebar;
+		}
+	}
+	if ( 'wp_inactive_widgets' === $id ) {
+		return array(
+			'id'   => 'wp_inactive_widgets',
+			'name' => __( 'Inactive widgets' ),
+		);
+	}
+	return null;
+}
+/**
 * Set the sidebar widget option to update sidebars.
 *
 * @since 2.2.0
 * @access private
 *
 	retrieve_widgets( true );
 }
 /**
-* Look for "lost" widgets, this has to run at least on each theme change.
+* Validates and remaps any "orphaned" widgets to wp_inactive_widgets sidebar,
+* and saves the widget settings. This has to run at least on each theme change.
+*
+* For example, let's say theme A has a "footer" sidebar, and theme B doesn't have one.
+* After switching from theme A to theme B, all the widgets previously assigned
+* to the footer would be inaccessible. This function detects this scenario, and
+* moves all the widgets previously assigned to the footer under wp_inactive_widgets.
+*
+* Despite the word "retrieve" in the name, this function actually updates the database
+* and the global `$sidebars_widgets`. For that reason it should not be run on front end,
+* unless the `$theme_changed` value is 'customize' (to bypass the database write).
 *
 * @since 2.8.0
 *
 * @global array $wp_registered_sidebars Registered sidebars.
 * @global array $sidebars_widgets
 		}
 	}
 	$sidebars_widgets['wp_inactive_widgets'] = array_merge( $lost_widgets, (array) $sidebars_widgets['wp_inactive_widgets'] );
 	if ( 'customize' !== $theme_changed ) {
+		// Update the widgets settings in the database.
 		wp_set_sidebars_widgets( $sidebars_widgets );
 	}
 	return $sidebars_widgets;
 }
 	$url          = esc_url_raw( strip_tags( $widget_rss['url'] ) );
 	$title        = isset( $widget_rss['title'] ) ? trim( strip_tags( $widget_rss['title'] ) ) : '';
 	$show_summary = isset( $widget_rss['show_summary'] ) ? (int) $widget_rss['show_summary'] : 0;
 	$show_author  = isset( $widget_rss['show_author'] ) ? (int) $widget_rss['show_author'] : 0;
 	$show_date    = isset( $widget_rss['show_date'] ) ? (int) $widget_rss['show_date'] : 0;
+	$error        = false;
+	$link         = '';
 	if ( $check_feed ) {
-		$rss   = fetch_feed( $url );
+		$rss = fetch_feed( $url );
-		$error = false;
-		$link  = '';
 		if ( is_wp_error( $rss ) ) {
 			$error = $rss->get_error_message();
 		} else {
 			$link = esc_url( strip_tags( $rss->get_permalink() ) );
 			while ( stristr( $link, 'http' ) !== $link ) {
 * unless a theme has removed support for widgets-block-editor or a plugin has
 * filtered the return value of this function.
 *
 * @since 5.8.0
 *
-* @return boolean Whether or not to use the block editor to manage widgets.
+* @return bool Whether to use the block editor to manage widgets.
 */
 function wp_use_widgets_block_editor() {
 	/**
-	 * Filters whether or not to use the block editor to manage widgets.
+	 * Filters whether to use the block editor to manage widgets.
 	 *
 	 * @since 5.8.0
 	 *
-	 * @param boolean $use_widgets_block_editor Whether or not to use the block editor to manage widgets.
+	 * @param bool $use_widgets_block_editor Whether to use the block editor to manage widgets.
 	 */
 	return apply_filters(
 		'use_widgets_block_editor',
 		get_theme_support( 'widgets-block-editor' )
 	);
 /**
 * Finds the sidebar that a given widget belongs to.
 *
 * @since 5.8.0
 *
-* @param string $widget_id The widget id to look for.
+* @param string $widget_id The widget ID to look for.
-* @return string|null The found sidebar's id, or null if it was not found.
+* @return string|null The found sidebar's ID, or null if it was not found.
 */
 function wp_find_widgets_sidebar( $widget_id ) {
 	foreach ( wp_get_sidebars_widgets() as $sidebar_id => $widget_ids ) {
 		foreach ( $widget_ids as $maybe_widget_id ) {
 			if ( $maybe_widget_id === $widget_id ) {
 /**
 * Assigns a widget to the given sidebar.
 *
 * @since 5.8.0
 *
-* @param string $widget_id  The widget id to assign.
+* @param string $widget_id  The widget ID to assign.
-* @param string $sidebar_id The sidebar id to assign to. If empty, the widget won't be added to any sidebar.
+* @param string $sidebar_id The sidebar ID to assign to. If empty, the widget won't be added to any sidebar.
 */
 function wp_assign_widget_to_sidebar( $widget_id, $sidebar_id ) {
 	$sidebars = wp_get_sidebars_widgets();
 	foreach ( $sidebars as $maybe_sidebar_id => $widgets ) {
 		foreach ( $widgets as $i => $maybe_widget_id ) {
 			if ( $widget_id === $maybe_widget_id && $sidebar_id !== $maybe_sidebar_id ) {
 				unset( $sidebars[ $maybe_sidebar_id ][ $i ] );
-				// We could technically break 2 here, but continue looping in case the id is duplicated.
+				// We could technically break 2 here, but continue looping in case the ID is duplicated.
 				continue 2;
 			}
 		}
 	}
 		$wp_scripts->query( 'wp-customize-widgets', 'enqueued' )
 	) {
 		if ( $wp_scripts->query( 'wp-editor', 'enqueued' ) ) {
 			_doing_it_wrong(
 				'wp_enqueue_script()',
-				'"wp-editor" script should not be enqueued together with the new widgets editor (wp-edit-widgets or wp-customize-widgets).',
+				sprintf(
+					/* translators: 1: 'wp-editor', 2: 'wp-edit-widgets', 3: 'wp-customize-widgets'. */
+					__( '"%1$s" script should not be enqueued together with the new widgets editor (%2$s or %3$s).' ),
+					'wp-editor',
+					'wp-edit-widgets',
+					'wp-customize-widgets'
+				),
 				'5.8.0'
 			);
 		}
 		if ( $wp_styles->query( 'wp-edit-post', 'enqueued' ) ) {
 			_doing_it_wrong(
 				'wp_enqueue_style()',
-				'"wp-edit-post" style should not be enqueued together with the new widgets editor (wp-edit-widgets or wp-customize-widgets).',
+				sprintf(
+					/* translators: 1: 'wp-edit-post', 2: 'wp-edit-widgets', 3: 'wp-customize-widgets'. */
+					__( '"%1$s" style should not be enqueued together with the new widgets editor (%2$s or %3$s).' ),
+					'wp-edit-post',
+					'wp-edit-widgets',
+					'wp-customize-widgets'
+				),
 				'5.8.0'
 			);
 		}
 	}
 }

changeset 19	3d72ae0968f4
parent 18	be944660c56a
child 21	48c4eec2b7e6