Merge branch 'trunk' into update/tt1-dependencies

src/wp-admin/includes/class-wp-comments-list-table.php

@@ -662,7 +662,7 @@ public function single_row( $item ) {
 				current_user_can( 'read_post', $comment->comment_post_ID )
 			)
 		) {
-			// The user has access to the post
+			// The user has access to the post and thus can see comments.
 		} else {
 			return false;
 		}

src/wp-admin/includes/class-wp-list-table.php

@@ -860,7 +860,7 @@ protected function comments_bubble( $post_id, $pending_comments ) {
 				current_user_can( 'read_post', $post_id )
 			)
 		) {
-			// The user has access to the post and thus can see comments
+			// The user has access to the post and thus can see comments.
 		} else {
 			return false;
 		}

src/wp-admin/includes/class-wp-ms-users-list-table.php

@@ -383,25 +383,30 @@ public function column_blogs( $user ) {
 
 			$path         = ( '/' === $site->path ) ? '' : $site->path;
 			$site_classes = array( 'site-' . $site->site_id );
+
 			/**
-			 * Filters the span class for a site listing on the mulisite user list table.
+			 * Filters the span class for a site listing on the multisite user list table.
 			 *
 			 * @since 5.2.0
 			 *
-			 * @param string[] $site_classes Array of class names used within the span tag. Default "site-#" with the site's network ID.
+			 * @param string[] $site_classes Array of class names used within the span tag.
+			 *                               Default "site-#" with the site's network ID.
 			 * @param int      $site_id      Site ID.
 			 * @param int      $network_id   Network ID.
 			 * @param WP_User  $user         WP_User object.
 			 */
 			$site_classes = apply_filters( 'ms_user_list_site_class', $site_classes, $site->userblog_id, $site->site_id, $user );
+
 			if ( is_array( $site_classes ) && ! empty( $site_classes ) ) {
 				$site_classes = array_map( 'sanitize_html_class', array_unique( $site_classes ) );
 				echo '<span class="' . esc_attr( implode( ' ', $site_classes ) ) . '">';
 			} else {
 				echo '<span>';
 			}
+
 			echo '<a href="' . esc_url( network_admin_url( 'site-info.php?id=' . $site->userblog_id ) ) . '">' . str_replace( '.' . get_network()->domain, '', $site->domain . $path ) . '</a>';
 			echo ' <small class="row-actions">';
+
 			$actions         = array();
 			$actions['edit'] = '<a href="' . esc_url( network_admin_url( 'site-info.php?id=' . $site->userblog_id ) ) . '">' . __( 'Edit' ) . '</a>';
 

src/wp-admin/includes/template.php

@@ -2540,20 +2540,20 @@ function compression_test() {
  *
  * @see get_submit_button()
  *
- * @param string       $text             The text of the button (defaults to 'Save Changes')
+ * @param string       $text             Optional. The text of the button. Defaults to 'Save Changes'.
  * @param string       $type             Optional. The type and CSS class(es) of the button. Core values
  *                                       include 'primary', 'small', and 'large'. Default 'primary'.
- * @param string       $name             The HTML name of the submit button. Defaults to "submit". If no
- *                                       id attribute is given in $other_attributes below, $name will be
- *                                       used as the button's id.
- * @param bool         $wrap             True if the output button should be wrapped in a paragraph tag,
- *                                       false otherwise. Defaults to true.
- * @param array|string $other_attributes Other attributes that should be output with the button, mapping
- *                                       attributes to their values, such as setting tabindex to 1, etc.
- *                                       These key/value attribute pairs will be output as attribute="value",
- *                                       where attribute is the key. Other attributes can also be provided
- *                                       as a string such as 'tabindex="1"', though the array format is
- *                                       preferred. Default null.
+ * @param string       $name             Optional. The HTML name of the submit button. If no `id` attribute
+ *                                       is given in the `$other_attributes` parameter, `$name` will be used
+ *                                       as the button's `id`. Default 'submit'.
+ * @param bool         $wrap             Optional. True if the output button should be wrapped in a paragraph tag,
+ *                                       false otherwise. Default true.
+ * @param array|string $other_attributes Optional. Other attributes that should be output with the button,
+ *                                       mapping attributes to their values, e.g. `array( 'id' => 'search-submit' )`.
+ *                                       These key/value attribute pairs will be output as `attribute="value"`,
+ *                                       where attribute is the key. Attributes can also be provided as a string,
+ *                                       e.g. `id="search-submit"`, though the array format is generally preferred.
+ *                                       Default null.
  */
 function submit_button( $text = null, $type = 'primary', $name = 'submit', $wrap = true, $other_attributes = null ) {
 	echo get_submit_button( $text, $type, $name, $wrap, $other_attributes );
@@ -2564,20 +2564,20 @@ function submit_button( $text = null, $type = 'primary', $name = 'submit', $wrap
  *
  * @since 3.1.0
  *
- * @param string       $text             Optional. The text of the button. Default 'Save Changes'.
+ * @param string       $text             Optional. The text of the button. Defaults to 'Save Changes'.
  * @param string       $type             Optional. The type and CSS class(es) of the button. Core values
  *                                       include 'primary', 'small', and 'large'. Default 'primary large'.
- * @param string       $name             Optional. The HTML name of the submit button. Defaults to "submit".
- *                                       If no id attribute is given in $other_attributes below, `$name` will
- *                                       be used as the button's id. Default 'submit'.
- * @param bool         $wrap             Optional. True if the output button should be wrapped in a paragraph
- *                                       tag, false otherwise. Default true.
+ * @param string       $name             Optional. The HTML name of the submit button. If no `id` attribute
+ *                                       is given in the `$other_attributes` parameter, `$name` will be used
+ *                                       as the button's `id`. Default 'submit'.
+ * @param bool         $wrap             Optional. True if the output button should be wrapped in a paragraph tag,
+ *                                       false otherwise. Default true.
  * @param array|string $other_attributes Optional. Other attributes that should be output with the button,
- *                                       mapping attributes to their values, such as `array( 'tabindex' => '1' )`.
- *                                       These attributes will be output as `attribute="value"`, such as
- *                                       `tabindex="1"`. Other attributes can also be provided as a string such
- *                                       as `tabindex="1"`, though the array format is typically cleaner.
- *                                       Default empty.
+ *                                       mapping attributes to their values, e.g. `array( 'id' => 'search-submit' )`.
+ *                                       These key/value attribute pairs will be output as `attribute="value"`,
+ *                                       where attribute is the key. Attributes can also be provided as a string,
+ *                                       e.g. `id="search-submit"`, though the array format is generally preferred.
+ *                                       Default empty string.
  * @return string Submit button HTML.
  */
 function get_submit_button( $text = '', $type = 'primary large', $name = 'submit', $wrap = true, $other_attributes = '' ) {

src/wp-admin/includes/user.php

@@ -638,7 +638,7 @@ function admin_created_user_email( $text ) {
  *
  * @since 5.6.0
  * @since 6.2.0 Allow insecure HTTP connections for the local environment.
- * @since 6.3.2 Validates the success and reject URLs to prevent javascript pseudo protocol being executed.
+ * @since 6.3.2 Validates the success and reject URLs to prevent `javascript` pseudo protocol from being executed.
  *
  * @param array   $request {
  *     The array of request data. All arguments are optional and may be empty.
@@ -700,12 +700,11 @@ function wp_is_authorize_application_password_request_valid( $request, $user ) {
 }
 
 /**
- * Validates the redirect URL protocol scheme. The protocol can be anything except http and javascript.
+ * Validates the redirect URL protocol scheme. The protocol can be anything except `http` and `javascript`.
  *
  * @since 6.3.2
  *
- * @param string $url - The redirect URL to be validated.
- *
+ * @param string $url The redirect URL to be validated.
  * @return true|WP_Error True if the redirect URL is valid, a WP_Error object otherwise.
  */
 function wp_is_authorize_application_redirect_url_valid( $url ) {
@@ -728,16 +727,17 @@ function wp_is_authorize_application_redirect_url_valid( $url ) {
 	 *
 	 * @since 6.3.2
 	 *
-	 * @param string[]  $bad_protocols Array of invalid protocols.
-	 * @param string    $url The redirect URL to be validated.
+	 * @param string[] $bad_protocols Array of invalid protocols.
+	 * @param string   $url The redirect URL to be validated.
 	 */
-	$invalid_protocols = array_map( 'strtolower', apply_filters( 'wp_authorize_application_redirect_url_invalid_protocols', $bad_protocols, $url ) );
+	$invalid_protocols = apply_filters( 'wp_authorize_application_redirect_url_invalid_protocols', $bad_protocols, $url );
+	$invalid_protocols = array_map( 'strtolower', $invalid_protocols );
 
 	$scheme   = wp_parse_url( $url, PHP_URL_SCHEME );
 	$host     = wp_parse_url( $url, PHP_URL_HOST );
 	$is_local = 'local' === wp_get_environment_type();
 
-	// validates if the proper URI format is applied to the $url
+	// Validates if the proper URI format is applied to the URL.
 	if ( empty( $host ) || empty( $scheme ) || in_array( strtolower( $scheme ), $invalid_protocols, true ) ) {
 		return new WP_Error(
 			'invalid_redirect_url_format',

src/wp-includes/block-template-utils.php

@@ -518,12 +518,12 @@ function _remove_theme_attribute_from_template_part_block( &$block ) {
  */
 function _build_block_template_result_from_file( $template_file, $template_type ) {
 	$default_template_types = get_default_block_template_types();
-	$template_content       = file_get_contents( $template_file['path'] );
 	$theme                  = get_stylesheet();
 
 	$template                 = new WP_Block_Template();
 	$template->id             = $theme . '//' . $template_file['slug'];
 	$template->theme          = $theme;
+	$template->content        = file_get_contents( $template_file['path'] );
 	$template->slug           = $template_file['slug'];
 	$template->source         = 'theme';
 	$template->type           = $template_type;
@@ -554,7 +554,7 @@ function _build_block_template_result_from_file( $template_file, $template_type
 		$before_block_visitor = make_before_block_visitor( $hooked_blocks, $template );
 		$after_block_visitor  = make_after_block_visitor( $hooked_blocks, $template );
 	}
-	$blocks            = parse_blocks( $template_content );
+	$blocks            = parse_blocks( $template->content );
 	$template->content = traverse_and_serialize_blocks( $blocks, $before_block_visitor, $after_block_visitor );
 
 	return $template;

src/wp-includes/blocks.php

@@ -1971,13 +1971,14 @@ function get_comments_pagination_arrow( $block, $pagination_type = 'next' ) {
 
 /**
  * Strips all HTML from the content of footnotes, and sanitizes the ID.
+ *
  * This function expects slashed data on the footnotes content.
  *
  * @access private
  * @since 6.3.2
  *
- * @param string $footnotes JSON encoded string of an array containing the content and ID of each footnote.
- * @return string Filtered content without any HTML on the footnote content and with the sanitized id.
+ * @param string $footnotes JSON-encoded string of an array containing the content and ID of each footnote.
+ * @return string Filtered content without any HTML on the footnote content and with the sanitized ID.
  */
 function _wp_filter_post_meta_footnotes( $footnotes ) {
 	$footnotes_decoded = json_decode( $footnotes, true );
@@ -1997,7 +1998,7 @@ function _wp_filter_post_meta_footnotes( $footnotes ) {
 }
 
 /**
- * Adds the filters to filter footnotes meta field.
+ * Adds the filters for footnotes meta field.
  *
  * @access private
  * @since 6.3.2
@@ -2007,7 +2008,7 @@ function _wp_footnotes_kses_init_filters() {
 }
 
 /**
- * Removes the filters that filter footnotes meta field.
+ * Removes the filters for footnotes meta field.
  *
  * @access private
  * @since 6.3.2
@@ -2017,7 +2018,7 @@ function _wp_footnotes_remove_filters() {
 }
 
 /**
- * Registers the filter of footnotes meta field if the user does not have unfiltered_html capability.
+ * Registers the filter of footnotes meta field if the user does not have `unfiltered_html` capability.
  *
  * @access private
  * @since 6.3.2
@@ -2030,12 +2031,12 @@ function _wp_footnotes_kses_init() {
 }
 
 /**
- * Initializes footnotes meta field filters when imported data should be filtered.
+ * Initializes the filters for footnotes meta field when imported data should be filtered.
  *
- * This filter is the last being executed on force_filtered_html_on_import.
- * If the input of the filter is true it means we are in an import situation and should
- * enable kses, independently of the user capabilities.
- * So in that case we call _wp_footnotes_kses_init_filters;
+ * This filter is the last one being executed on {@see 'force_filtered_html_on_import'}.
+ * If the input of the filter is true, it means we are in an import situation and should
+ * enable kses, independently of the user capabilities. So in that case we call
+ * _wp_footnotes_kses_init_filters().
  *
  * @access private
  * @since 6.3.2
@@ -2044,7 +2045,7 @@ function _wp_footnotes_kses_init() {
  * @return string Input argument of the filter.
  */
 function _wp_footnotes_force_filtered_html_on_import_filter( $arg ) {
-	// force_filtered_html_on_import is true we need to init the global styles kses filters.
+	// If `force_filtered_html_on_import` is true, we need to init the global styles kses filters.
 	if ( $arg ) {
 		_wp_footnotes_kses_init_filters();
 	}

src/wp-includes/html-api/class-wp-html-processor.php

@@ -99,12 +99,16 @@
  *
  * The following list specifies the HTML tags that _are_ supported:
  *
+ *  - Containers: ADDRESS, BLOCKQUOTE, DETAILS, DIALOG, DIV, FOOTER, HEADER, MAIN, MENU, SPAN, SUMMARY.
+ *  - Form elements: BUTTON, FIELDSET, SEARCH.
+ *  - Formatting elements: B, BIG, CODE, EM, FONT, I, SMALL, STRIKE, STRONG, TT, U.
+ *  - Heading elements: HGROUP.
  *  - Links: A.
- *  - The formatting elements: B, BIG, CODE, EM, FONT, I, SMALL, STRIKE, STRONG, TT, U.
- *  - Containers: DIV, FIGCAPTION, FIGURE, SPAN.
- *  - Form elements: BUTTON.
+ *  - Lists: DL.
+ *  - Media elements: FIGCAPTION, FIGURE, IMG.
  *  - Paragraph: P.
- *  - Void elements: IMG.
+ *  - Sectioning elements: ARTICLE, ASIDE, NAV, SECTION
+ *  - Deprecated elements: CENTER, DIR
  *
  * ### Supported markup
  *
@@ -621,11 +625,29 @@ private function step_in_body() {
 			 * > "fieldset", "figcaption", "figure", "footer", "header", "hgroup",
 			 * > "main", "menu", "nav", "ol", "p", "search", "section", "summary", "ul"
 			 */
+			case '+ADDRESS':
+			case '+ARTICLE':
+			case '+ASIDE':
 			case '+BLOCKQUOTE':
+			case '+CENTER':
+			case '+DETAILS':
+			case '+DIALOG':
+			case '+DIR':
 			case '+DIV':
+			case '+DL':
+			case '+FIELDSET':
 			case '+FIGCAPTION':
 			case '+FIGURE':
+			case '+FOOTER':
+			case '+HEADER':
+			case '+HGROUP':
+			case '+MAIN':
+			case '+MENU':
+			case '+NAV':
 			case '+P':
+			case '+SEARCH':
+			case '+SECTION':
+			case '+SUMMARY':
 				if ( $this->state->stack_of_open_elements->has_p_in_button_scope() ) {
 					$this->close_a_p_element();
 				}
@@ -639,11 +661,29 @@ private function step_in_body() {
 			 * > "figcaption", "figure", "footer", "header", "hgroup", "listing", "main",
 			 * > "menu", "nav", "ol", "pre", "search", "section", "summary", "ul"
 			 */
+			case '-ADDRESS':
+			case '-ARTICLE':
+			case '-ASIDE':
 			case '-BLOCKQUOTE':
 			case '-BUTTON':
+			case '-CENTER':
+			case '-DETAILS':
+			case '-DIALOG':
+			case '-DIR':
 			case '-DIV':
+			case '-DL':
+			case '-FIELDSET':
 			case '-FIGCAPTION':
 			case '-FIGURE':
+			case '-FOOTER':
+			case '-HEADER':
+			case '-HGROUP':
+			case '-MAIN':
+			case '-MENU':
+			case '-NAV':
+			case '-SEARCH':
+			case '-SECTION':
+			case '-SUMMARY':
 				if ( ! $this->state->stack_of_open_elements->has_element_in_scope( $tag_name ) ) {
 					// @TODO: Report parse error.
 					// Ignore the token.

src/wp-includes/html-api/class-wp-html-tag-processor.php

@@ -116,7 +116,7 @@
  *
  * Example:
  *
- *     if ( $tags->next_tag( array( 'class' => 'wp-group-block' ) ) ) {
+ *     if ( $tags->next_tag( array( 'class_name' => 'wp-group-block' ) ) ) {
  *         $tags->set_attribute( 'title', 'This groups the contained content.' );
  *         $tags->remove_attribute( 'data-test-id' );
  *     }

src/wp-includes/media.php

@@ -2636,10 +2636,10 @@ function gallery_shortcode( $attr ) {
 	if ( ! empty( $post_parent_id ) ) {
 		$post_parent = get_post( $post_parent_id );
 
-		// terminate the shortcode execution if user cannot read the post or password-protected
-		if (
-		( ! is_post_publicly_viewable( $post_parent->ID ) && ! current_user_can( 'read_post', $post_parent->ID ) )
-		|| post_password_required( $post_parent ) ) {
+		// Terminate the shortcode execution if the user cannot read the post or it is password-protected.
+		if ( ! is_post_publicly_viewable( $post_parent->ID ) && ! current_user_can( 'read_post', $post_parent->ID )
+			|| post_password_required( $post_parent )
+		) {
 			return '';
 		}
 	}
@@ -2979,7 +2979,7 @@ function wp_playlist_shortcode( $attr ) {
 	if ( ! empty( $args['post_parent'] ) ) {
 		$post_parent = get_post( $id );
 
-		// terminate the shortcode execution if user cannot read the post or password-protected
+		// Terminate the shortcode execution if the user cannot read the post or it is password-protected.
 		if ( ! current_user_can( 'read_post', $post_parent->ID ) || post_password_required( $post_parent ) ) {
 			return '';
 		}

src/wp-includes/rest-api/class-wp-rest-server.php

@@ -467,17 +467,19 @@ public function serve_request( $path = null ) {
 		$this->set_status( $code );
 
 		/**
-		 * Filters whether to send nocache headers on a REST API request.
+		 * Filters whether to send no-cache headers on a REST API request.
 		 *
 		 * @since 4.4.0
-		 * @since 6.3.2 Moved the block to catch the filter added on rest_cookie_check_errors() from rest-api.php
+		 * @since 6.3.2 Moved the block to catch the filter added on rest_cookie_check_errors() from wp-includes/rest-api.php.
 		 *
 		 * @param bool $rest_send_nocache_headers Whether to send no-cache headers.
 		 */
 		$send_no_cache_headers = apply_filters( 'rest_send_nocache_headers', is_user_logged_in() );
 
-		// send no cache headers if the $send_no_cache_headers is true
-		// OR if the HTTP_X_HTTP_METHOD_OVERRIDE is used but resulted a 4x response code.
+		/*
+		 * Send no-cache headers if $send_no_cache_headers is true,
+		 * OR if the HTTP_X_HTTP_METHOD_OVERRIDE is used but resulted a 4xx response code.
+		 */
 		if ( $send_no_cache_headers || ( true === $method_overridden && strpos( $code, '4' ) === 0 ) ) {
 			foreach ( wp_get_nocache_headers() as $header => $header_value ) {
 				if ( empty( $header_value ) ) {