#64099: Improve hoisted stylesheet ordering

phpcompat.xml.dist

@@ -114,4 +114,12 @@
 		<exclude-pattern>/sodium_compat/src/PHP52/SplFixedArray\.php$</exclude-pattern>
 	</rule>
 
+	<!--
+		Excluded while waiting for PHPCompatibility v10.
+		See <https://github.com/PHPCompatibility/PHPCompatibility/issues/1481>.
+	-->
+	<rule ref="PHPCompatibility.FunctionDeclarations.NewClosure.ThisFoundOutsideClass">
+		<exclude-pattern>/src/wp-includes/script-loader\.php$</exclude-pattern>
+	</rule>
+
 </ruleset>

src/wp-includes/class-wp-block-type-registry.php

@@ -150,7 +150,7 @@ public function get_registered( $name ) {
 	 *
 	 * @since 5.0.0
 	 *
-	 * @return WP_Block_Type[] Associative array of `$block_type_name => $block_type` pairs.
+	 * @return array<string, WP_Block_Type> Associative array of `$block_type_name => $block_type` pairs.
 	 */
 	public function get_all_registered() {
 		return $this->registered_block_types;

src/wp-includes/script-loader.php

@@ -3607,20 +3607,23 @@ function wp_load_classic_theme_block_styles_on_demand() {
 	// The following two filters are added by default for block themes in _add_default_theme_supports().
 
 	/*
-	 * Load separate block styles so that the large block-library stylesheet is not enqueued unconditionally,
-	 * and so that block-specific styles will only be enqueued when they are used on the page.
-	 * A priority of zero allows for this to be easily overridden by themes which wish to opt out.
+	 * Load separate block styles so that the large block-library stylesheet is not enqueued unconditionally, and so
+	 * that block-specific styles will only be enqueued when they are used on the page. A priority of zero allows for
+	 * this to be easily overridden by themes which wish to opt out. If a site has explicitly opted out of loading
+	 * separate block styles, then abort.
 	 */
 	add_filter( 'should_load_separate_core_block_assets', '__return_true', 0 );
+	if ( ! wp_should_load_separate_core_block_assets() ) {
+		return;
+	}
 
 	/*
 	 * Also ensure that block assets are loaded on demand (although the default value is from should_load_separate_core_block_assets).
-	 * As above, a priority of zero allows for this to be easily overridden by themes which wish to opt out.
+	 * As above, a priority of zero allows for this to be easily overridden by themes which wish to opt out. If a site
+	 * has explicitly opted out of loading block styles on demand, then abort.
 	 */
 	add_filter( 'should_load_block_assets_on_demand', '__return_true', 0 );
-
-	// If a site has explicitly opted out of loading block styles on demand via filters with priorities higher than above, then abort.
-	if ( ! wp_should_load_separate_core_block_assets() || ! wp_should_load_block_assets_on_demand() ) {
+	if ( ! wp_should_load_block_assets_on_demand() ) {
 		return;
 	}
 
@@ -3642,15 +3645,6 @@ function wp_hoist_late_printed_styles() {
 		return;
 	}
 
-	/*
-	 * While normally late styles are printed, there is a filter to disable prevent this, so this makes sure they are
-	 * printed. Note that this filter was intended to control whether to print the styles queued too late for the HTML
-	 * head. This filter was introduced in <https://core.trac.wordpress.org/ticket/9346>. However, with the template
-	 * enhancement output buffer, essentially no style can be enqueued too late, because an output buffer filter can
-	 * always hoist it to the HEAD.
-	 */
-	add_filter( 'print_late_styles', '__return_true', PHP_INT_MAX );
-
 	/*
 	 * Print a placeholder comment where the late styles can be hoisted from the footer to be printed in the header
 	 * by means of a filter below on the template enhancement output buffer.
@@ -3660,11 +3654,44 @@ function wp_hoist_late_printed_styles() {
 	wp_add_inline_style( 'wp-block-library', $placeholder );
 
 	// Wrap print_late_styles() with a closure that captures the late-printed styles.
-	$printed_late_styles = '';
-	$capture_late_styles = static function () use ( &$printed_late_styles ) {
+	$printed_block_styles = '';
+	$printed_late_styles  = '';
+	$capture_late_styles  = static function () use ( &$printed_block_styles, &$printed_late_styles ) {
+		global $concatenate_scripts;
+		script_concat_settings();
+
+		// Print the styles related to on-demand block enqueues.
+		$all_block_style_handles = array();
+		foreach ( WP_Block_Type_Registry::get_instance()->get_all_registered() as $block_type ) {
+			foreach ( $block_type->style_handles as $style_handle ) {
+				$all_block_style_handles[] = $style_handle;
+			}
+		}
+		$all_block_style_handles = array_merge(
+			$all_block_style_handles,
+			array( 'global-styles', 'core-block-supports', 'block-style-variation-styles' ) // TODO: What else?
+		);
+
+		$enqueued_block_styles = array_values( array_intersect( $all_block_style_handles, wp_styles()->queue ) );
+		if ( count( $enqueued_block_styles ) > 0 ) {
+			wp_styles()->do_concat = $concatenate_scripts;
+			ob_start();
+			wp_styles()->do_items( $enqueued_block_styles );
+			_print_styles(); // TODO: Is this needed?
+			$printed_block_styles = ob_get_clean();
+			wp_styles()->reset();
+		}
+
+		/*
+		 * Print remaining styles not related to blocks. This is the same logic as in print_late_styles(), but without
+		 * the filter to control whether late styles are printed (since they are being hoisted anyway).
+		 */
+		wp_styles()->do_concat = $concatenate_scripts;
 		ob_start();
-		print_late_styles();
+		wp_styles()->do_footer_items();
+		_print_styles(); // TODO: Is this needed?
 		$printed_late_styles = ob_get_clean();
+		wp_styles()->reset();
 	};
 
 	/*
@@ -3695,65 +3722,76 @@ static function () use ( $capture_late_styles ) {
 	// Replace placeholder with the captured late styles.
 	add_filter(
 		'wp_template_enhancement_output_buffer',
-		function ( $buffer ) use ( $placeholder, &$printed_late_styles ) {
+		function ( $buffer ) use ( $placeholder, &$printed_block_styles, &$printed_late_styles ) {
 
 			// Anonymous subclass of WP_HTML_Tag_Processor which exposes underlying bookmark spans.
 			$processor = new class( $buffer ) extends WP_HTML_Tag_Processor {
-				public function get_span(): WP_HTML_Span {
-					$instance = $this; // phpcs:ignore PHPCompatibility.FunctionDeclarations.NewClosure.ThisFoundOutsideClass -- It is inside an anonymous class.
-					$instance->set_bookmark( 'here' );
-					return $instance->bookmarks['here'];
+				/**
+				 * Gets the span for the current token.
+				 *
+				 * @return WP_HTML_Span Current token span.
+				 */
+				private function get_span(): WP_HTML_Span {
+					$this->set_bookmark( 'here' ); // TODO: What if this fails?
+					return $this->bookmarks['here'];
+				}
+
+				/**
+				 * Inserts text before the current token.
+				 *
+				 * @param string $text Text to insert.
+				 */
+				public function insert_before( string $text ) {
+					$this->lexical_updates[] = new WP_HTML_Text_Replacement( $this->get_span()->start, 0, $text );
+				}
+
+				/**
+				 * Inserts text after the current token.
+				 *
+				 * @param string $text Text to insert.
+				 */
+				public function insert_after( string $text ) {
+					$span = $this->get_span();
+
+					$this->lexical_updates[] = new WP_HTML_Text_Replacement( $span->start + $span->length, 0, $text );
 				}
 			};
 
-			// Loop over STYLE tags.
+			// TODO: If there are no block styles to print, it would be nice to not have to replace the placeholder comment.
+			// Insert block styles right after wp-block-library (if it is present), and then insert any remaining styles at </head>.
 			while ( $processor->next_tag( array( 'tag_closers' => 'visit' ) ) ) {
-
-				// We've encountered the inline style for the 'wp-block-library' stylesheet which probably has the placeholder comment.
 				if (
-					! $processor->is_tag_closer() &&
 					'STYLE' === $processor->get_tag() &&
 					'wp-block-library-inline-css' === $processor->get_attribute( 'id' )
 				) {
-					// If the inline style lacks the placeholder comment, then we have to continue until we get to </HEAD> to append the styles there.
+					// If the inline style lacks the placeholder comment, then all the styles will be inserted below at </head>.
 					$css_text = $processor->get_modifiable_text();
 					if ( ! str_contains( $css_text, $placeholder ) ) {
 						continue;
 					}
 
 					// Remove the placeholder now that we've located the inline style.
 					$processor->set_modifiable_text( str_replace( $placeholder, '', $css_text ) );
-					$buffer = $processor->get_updated_html();
 
 					// Insert the $printed_late_styles immediately after the closing inline STYLE tag. This preserves the CSS cascade.
-					$span   = $processor->get_span();
-					$buffer = implode(
-						'',
-						array(
-							substr( $buffer, 0, $span->start + $span->length ),
-							$printed_late_styles,
-							substr( $buffer, $span->start + $span->length ),
-						)
-					);
-					break;
-				}
+					if ( '' !== $printed_block_styles ) {
+						$processor->insert_after( $printed_block_styles );
 
-				// As a fallback, append the hoisted late styles to the end of the HEAD.
-				if ( $processor->is_tag_closer() && 'HEAD' === $processor->get_tag() ) {
-					$span   = $processor->get_span();
-					$buffer = implode(
-						'',
-						array(
-							substr( $buffer, 0, $span->start ),
-							$printed_late_styles,
-							substr( $buffer, $span->start ),
-						)
-					);
+						// Prevent printing them again at </head>.
+						$printed_block_styles = '';
+					}
+
+					// If there aren't any late styles, there's no need to continue to finding </head>.
+					if ( '' === $printed_late_styles ) {
+						break;
+					}
+				} elseif ( 'HEAD' === $processor->get_tag() && $processor->is_tag_closer() ) {
+					$processor->insert_before( $printed_block_styles . $printed_late_styles );
 					break;
 				}
 			}
 
-			return $buffer;
+			return $processor->get_updated_html();
 		}
 	);
 }