Changeset 61008 for trunk/src/wp-includes/script-loader.php

Timestamp:

10/21/2025 05:59:38 AM (12 months ago)

Author:

westonruter

Message:

Script Loader: Load block styles on demand in classic themes via the template enhancement output buffer.

• This applies in classic themes when a site has not opted out of the template enhancement buffer by filtering wp_should_output_buffer_template_for_enhancement off.
• Both should_load_separate_core_block_assets and should_load_block_assets_on_demand are filtered on, as otherwise they are only enabled by default in block themes.
• Any style enqueued after wp_head and printed via print_late_styles() will get hoisted up to be inserted right after the wp-block-library inline style in the HEAD.
• The result is a >10% benchmarked improvement in LCP for core classic themes due to a ~100KB reduction in the amount of CSS unconditionally being served with every page load.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/10288

Follow-up to [60936].

Props sjapaget, westonruter, peterwilsoncc, dmsnell, mindctrl.
See #43258.
Fixes #64099.

File:

• trunk/src/wp-includes/script-loader.php (modified) (3 diffs)

trunk/src/wp-includes/script-loader.php

@@ -2265 +2265 @@
  * Private, for use in *_footer_scripts hooks
  *
+ * In classic themes, when block styles are loaded on demand via {@see wp_load_classic_theme_block_styles_on_demand()},
+ * this function is replaced by a closure in {@see wp_hoist_late_printed_styles()} which will capture the output of
+ * {@see print_late_styles()} before printing footer scripts as usual. The captured late-printed styles are then hoisted
+ * to the HEAD by means of the template enhancement output buffer.
+ *
  * @since 3.3.0
  */
@@ -3233 +3238 @@
  */
 function wp_enqueue_stored_styles( $options = array() ) {
+        // Note: Styles printed at wp_footer for classic themes may still end up in the head due to wp_load_classic_theme_block_styles_on_demand().
         $is_block_theme   = wp_is_block_theme();
         $is_classic_theme = ! $is_block_theme;
@@ -3471 +3477 @@
 
 /**
+ * Adds hooks to load block styles on demand in classic themes.
+ *
+ * @since 6.9.0
+ */
+function wp_load_classic_theme_block_styles_on_demand() {
+        if ( wp_is_block_theme() ) {
+                return;
+        }
+
+        /*
+         * Make sure that wp_should_output_buffer_template_for_enhancement() returns true even if there aren't any
+         * `wp_template_enhancement_output_buffer` filters added, but do so at priority zero so that applications which
+         * wish to stream responses can more easily turn this off.
+         */
+        add_filter( 'wp_should_output_buffer_template_for_enhancement', '__return_true', 0 );
+
+        if ( ! wp_should_output_buffer_template_for_enhancement() ) {
+                return;
+        }
+
+        /*
+         * 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.
+         */
+        add_filter( 'should_load_separate_core_block_assets', '__return_true', 0 );
+
+        // Also ensure that block assets are loaded on demand (although the default value is from should_load_separate_core_block_assets).
+        add_filter( 'should_load_block_assets_on_demand', '__return_true', 0 );
+
+        // Add hooks which require the presence of the output buffer. Ideally the above two filters could be added here, but they run too early.
+        add_action( 'wp_template_enhancement_output_buffer_started', 'wp_hoist_late_printed_styles' );
+}
+
+/**
+ * Adds the hooks needed for CSS output to be delayed until after the content of the page has been established.
+ *
+ * @since 6.9.0
+ *
+ * @see wp_load_classic_theme_block_styles_on_demand()
+ * @see _wp_footer_scripts()
+ */
+function wp_hoist_late_printed_styles() {
+        // Skip the embed template on-demand styles aren't relevant, and there is no wp_head action.
+        if ( is_embed() ) {
+                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.
+         */
+        $placeholder = sprintf( '/*%s*/', uniqid( 'wp_late_styles_placeholder:' ) );
+
+        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 ) {
+                ob_start();
+                print_late_styles();
+                $printed_late_styles = ob_get_clean();
+        };
+
+        /*
+         * If _wp_footer_scripts() was unhooked from the wp_print_footer_scripts action, or if wp_print_footer_scripts()
+         * was unhooked from running at the wp_footer action, then only add a callback to wp_footer which will capture the
+         * late-printed styles.
+         *
+         * Otherwise, in the normal case where _wp_footer_scripts() will run at the wp_print_footer_scripts action, then
+         * swap out _wp_footer_scripts() with an alternative which captures the printed styles (for hoisting to HEAD) before
+         * proceeding with printing the footer scripts.
+         */
+        $wp_print_footer_scripts_priority = has_action( 'wp_print_footer_scripts', '_wp_footer_scripts' );
+        if ( false === $wp_print_footer_scripts_priority || false === has_action( 'wp_footer', 'wp_print_footer_scripts' ) ) {
+                // The normal priority for wp_print_footer_scripts() is to run at 20.
+                add_action( 'wp_footer', $capture_late_styles, 20 );
+        } else {
+                remove_action( 'wp_print_footer_scripts', '_wp_footer_scripts', $wp_print_footer_scripts_priority );
+                add_action(
+                        'wp_print_footer_scripts',
+                        static function () use ( $capture_late_styles ) {
+                                $capture_late_styles();
+                                print_footer_scripts();
+                        },
+                        $wp_print_footer_scripts_priority
+                );
+        }
+
+        // Replace placeholder with the captured late styles.
+        add_filter(
+                'wp_template_enhancement_output_buffer',
+                function ( $buffer ) use ( $placeholder, &$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'];
+                                }
+                        };
+
+                        // Loop over STYLE tags.
+                        while ( $processor->next_tag( array( 'tag_name' => 'STYLE' ) ) ) {
+                                // Skip to the next if this is not the inline style for the wp-block-library stylesheet (which contains the placeholder).
+                                if ( 'wp-block-library-inline-css' !== $processor->get_attribute( 'id' ) ) {
+                                        continue;
+                                }
+
+                                // If the inline style lacks the placeholder comment, then something went wrong and we need to abort.
+                                $css_text = $processor->get_modifiable_text();
+                                if ( ! str_contains( $css_text, $placeholder ) ) {
+                                        break;
+                                }
+
+                                // 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;
+                        }
+
+                        return $buffer;
+                }
+        );
+}
+
+/**
  * Return the corresponding JavaScript `dataset` name for an attribute
  * if it represents a custom data attribute, or `null` if not.