diff --git a/src/wp-includes/blocks.php b/src/wp-includes/blocks.php index 34f1d921dda66..235e4f3501ceb 100644 --- a/src/wp-includes/blocks.php +++ b/src/wp-includes/blocks.php @@ -304,7 +304,7 @@ function register_block_style_handle( $metadata, $field_name, $index = 0 ) { $is_core_block = isset( $metadata['file'] ) && str_starts_with( $metadata['file'], $wpinc_path_norm ); // Skip registering individual styles for each core block when a bundled version provided. - if ( $is_core_block && ! wp_should_load_separate_core_block_assets() ) { + if ( $is_core_block && ! wp_should_load_block_assets_on_demand() ) { return false; } @@ -457,7 +457,7 @@ function register_block_type_from_metadata( $file_or_folder, $args = array() ) { if ( ! isset( $metadata['style'] ) ) { $metadata['style'] = "wp-block-$block_name"; } - if ( current_theme_supports( 'wp-block-styles' ) && wp_should_load_separate_core_block_assets() ) { + if ( current_theme_supports( 'wp-block-styles' ) && wp_should_load_block_assets_on_demand() ) { $metadata['style'] = (array) $metadata['style']; $metadata['style'][] = "wp-block-{$block_name}-theme"; } diff --git a/src/wp-includes/blocks/index.php b/src/wp-includes/blocks/index.php index 98615ea1ba766..2e5f84151f3c4 100644 --- a/src/wp-includes/blocks/index.php +++ b/src/wp-includes/blocks/index.php @@ -29,7 +29,7 @@ function register_core_block_style_handles() { $wp_version = wp_get_wp_version(); - if ( ! wp_should_load_separate_core_block_assets() ) { + if ( ! wp_should_load_block_assets_on_demand() ) { return; } diff --git a/src/wp-includes/deprecated.php b/src/wp-includes/deprecated.php index e692772f272ae..5303be78a34b2 100644 --- a/src/wp-includes/deprecated.php +++ b/src/wp-includes/deprecated.php @@ -6406,3 +6406,46 @@ function wp_create_block_style_variation_instance_name( $block, $variation ) { _deprecated_function( __FUNCTION__, '6.7.0', 'wp_unique_id' ); return $variation . '--' . md5( serialize( $block ) ); } + +/** + * Checks whether separate styles should be loaded for core blocks on-render. + * + * When this function returns true, other functions ensure that core blocks + * only load their assets on-render, and each block loads its own, individual + * assets. Third-party blocks only load their assets when rendered. + * + * When this function returns false, all core block assets are loaded regardless + * of whether they are rendered in a page or not, because they are all part of + * the `block-library/style.css` file. Assets for third-party blocks are always + * enqueued regardless of whether they are rendered or not. + * + * This only affects front end and not the block editor screens. + * + * @see wp_enqueue_registered_block_scripts_and_styles() + * @see register_block_style_handle() + * + * @since 5.8.0 + * @deprecated 6.8.0 Use {@see 'wp_should_load_block_assets_on_demand'} instead. + * + * @return bool Whether separate assets will be loaded. + */ +function wp_should_load_separate_core_block_assets() { + _deprecated_function( __FUNCTION__, '6.8.0', 'wp_should_load_block_assets_on_demand' ); + + if ( is_admin() || is_feed() || wp_is_rest_endpoint() ) { + return false; + } + + /** + * Filters whether block styles should be loaded separately. + * + * Returning false loads all core block assets, regardless of whether they are rendered + * in a page or not. Returning true loads core block assets only when they are rendered. + * + * @since 5.8.0 + * + * @param bool $load_separate_assets Whether separate assets will be loaded. + * Default false (all block assets are loaded, even when not used). + */ + return apply_filters( 'should_load_separate_core_block_assets', false ); +} diff --git a/src/wp-includes/global-styles-and-settings.php b/src/wp-includes/global-styles-and-settings.php index f40d4a5e9863e..7815bb4993a7c 100644 --- a/src/wp-includes/global-styles-and-settings.php +++ b/src/wp-includes/global-styles-and-settings.php @@ -260,7 +260,7 @@ function wp_add_global_styles_for_blocks() { foreach ( $block_nodes as $metadata ) { $block_css = $tree->get_styles_for_block( $metadata ); - if ( ! wp_should_load_separate_core_block_assets() ) { + if ( ! wp_should_load_block_assets_on_demand() ) { wp_add_inline_style( 'global-styles', $block_css ); continue; } @@ -268,7 +268,7 @@ function wp_add_global_styles_for_blocks() { $stylesheet_handle = 'global-styles'; /* - * When `wp_should_load_separate_core_block_assets()` is true, block styles are + * When `wp_should_load_block_assets_on_demand()` is true, block styles are * enqueued for each block on the page in class WP_Block's render function. * This means there will be a handle in the styles queue for each of those blocks. * Block-specific global styles should be attached to the global-styles handle, but diff --git a/src/wp-includes/script-loader.php b/src/wp-includes/script-loader.php index 61409c477638f..1bb86627f2329 100644 --- a/src/wp-includes/script-loader.php +++ b/src/wp-includes/script-loader.php @@ -1777,7 +1777,7 @@ function wp_default_styles( $styles ) { $handle = 'wp-' . $package; $path = "/wp-includes/css/dist/$package/style$suffix.css"; - if ( 'block-library' === $package && wp_should_load_separate_core_block_assets() ) { + if ( 'block-library' === $package && wp_should_load_block_assets_on_demand() ) { $path = "/wp-includes/css/dist/$package/common$suffix.css"; } $styles->add( $handle, $path, $dependencies ); @@ -2439,7 +2439,7 @@ function wp_common_block_scripts_and_styles() { wp_enqueue_style( 'wp-block-library' ); - if ( current_theme_supports( 'wp-block-styles' ) && ! wp_should_load_separate_core_block_assets() ) { + if ( current_theme_supports( 'wp-block-styles' ) && ! wp_should_load_block_assets_on_demand() ) { wp_enqueue_style( 'wp-block-library-theme' ); } @@ -2486,7 +2486,7 @@ static function ( $node ) { * @since 5.8.0 */ function wp_enqueue_global_styles() { - $separate_assets = wp_should_load_separate_core_block_assets(); + $separate_assets = wp_should_load_block_assets_on_demand(); $is_block_theme = wp_is_block_theme(); $is_classic_theme = ! $is_block_theme; @@ -2566,43 +2566,69 @@ function wp_should_load_block_editor_scripts_and_styles() { } /** - * Checks whether separate styles should be loaded for core blocks on-render. + * Determines whether block assets should be loaded on demand. * - * When this function returns true, other functions ensure that core blocks - * only load their assets on-render, and each block loads its own, individual - * assets. Third-party blocks only load their assets when rendered. + * This function checks if the current request context allows for conditional + * loading of block assets. When enabled, only the block assets for blocks + * that are actually rendered on the page will be loaded. This approach + * improves performance by avoiding the loading of unnecessary stylesheets + * and scripts, particularly in cases where blocks are not present in the + * content being rendered. * - * When this function returns false, all core block assets are loaded regardless - * of whether they are rendered in a page or not, because they are all part of - * the `block-library/style.css` file. Assets for third-party blocks are always - * enqueued regardless of whether they are rendered or not. + * When the function returns true, individual stylesheets for core blocks + * will be used instead of loading the full wp-block-library stylesheet. + * This behavior is a side effect of the primary purpose of loading block + * assets on demand, which also includes third-party blocks. * - * This only affects front end and not the block editor screens. + * The function will return false under the following conditions: + * - If the current request is in the admin area + * - If the current request is for an RSS feed + * - If the current request is a REST API endpoint * - * @see wp_enqueue_registered_block_scripts_and_styles() - * @see register_block_style_handle() + * This function is a key component of the block asset management system + * introduced in WordPress 5.8. It is recommended to use the associated + * filter, 'wp_should_load_block_assets_on_demand', to modify the loading + * behavior in custom implementations. * - * @since 5.8.0 + * Formerly wp_should_load_separate_core_block_assets(), introduced in 5.8.0. + * + * @since 6.8.0 * - * @return bool Whether separate assets will be loaded. + * @return bool False if all block assets should be loaded, true if block + * assets should be loaded only when needed (i.e., on demand). */ -function wp_should_load_separate_core_block_assets() { +function wp_should_load_block_assets_on_demand() { if ( is_admin() || is_feed() || wp_is_rest_endpoint() ) { return false; } /** - * Filters whether block styles should be loaded separately. + * Backward compatibility for the deprecated `should_load_separate_core_block_assets` filter. + * This filter is documented in wp-includes/deprecated.php + */ + $should_load = apply_filters_deprecated( + 'should_load_separate_core_block_assets', + array( false ), + '6.8.0', + 'wp_should_load_block_assets_on_demand' + ); + + /** + * Filters whether block assets should be loaded on demand. * - * Returning false loads all core block assets, regardless of whether they are rendered - * in a page or not. Returning true loads core block assets only when they are rendered. + * This filter customizes the loading behavior of block styles and scripts. + * When set to true, only the assets for blocks actually rendered on the + * page will be loaded, improving performance by preventing unnecessary + * asset loading. Individual stylesheets for core blocks will be used + * instead of the full wp-block-library stylesheet in this case. * - * @since 5.8.0 + * @since 6.8.0 * * @param bool $load_separate_assets Whether separate assets will be loaded. - * Default false (all block assets are loaded, even when not used). + * Default false (all block assets are loaded, + * even when not used). */ - return apply_filters( 'should_load_separate_core_block_assets', false ); + return apply_filters( 'wp_should_load_block_assets_on_demand', $should_load ); } /** @@ -2616,7 +2642,7 @@ function wp_should_load_separate_core_block_assets() { function wp_enqueue_registered_block_scripts_and_styles() { global $current_screen; - if ( wp_should_load_separate_core_block_assets() ) { + if ( wp_should_load_block_assets_on_demand() ) { return; } @@ -2665,7 +2691,7 @@ function enqueue_block_styles_assets() { if ( isset( $style_properties['style_handle'] ) ) { // If the site loads separate styles per-block, enqueue the stylesheet on render. - if ( wp_should_load_separate_core_block_assets() ) { + if ( wp_should_load_block_assets_on_demand() ) { add_filter( 'render_block', static function ( $html, $block ) use ( $block_name, $style_properties ) { @@ -2687,7 +2713,7 @@ static function ( $html, $block ) use ( $block_name, $style_properties ) { $handle = 'wp-block-library'; // If the site loads separate styles per-block, check if the block has a stylesheet registered. - if ( wp_should_load_separate_core_block_assets() ) { + if ( wp_should_load_block_assets_on_demand() ) { $block_stylesheet_handle = generate_block_asset_handle( $block_name, 'style' ); if ( isset( $wp_styles->registered[ $block_stylesheet_handle ] ) ) { @@ -3254,7 +3280,7 @@ function wp_enqueue_block_style( $block_name, $args ) { }; $hook = did_action( 'wp_enqueue_scripts' ) ? 'wp_footer' : 'wp_enqueue_scripts'; - if ( wp_should_load_separate_core_block_assets() ) { + if ( wp_should_load_block_assets_on_demand() ) { /** * Callback function to register and enqueue styles. * diff --git a/src/wp-includes/theme.php b/src/wp-includes/theme.php index 1a9b2479ad7e2..213eb0bc756e2 100644 --- a/src/wp-includes/theme.php +++ b/src/wp-includes/theme.php @@ -4394,7 +4394,7 @@ function _add_default_theme_supports() { add_theme_support( 'html5', array( 'comment-form', 'comment-list', 'search-form', 'gallery', 'caption', 'style', 'script' ) ); add_theme_support( 'automatic-feed-links' ); - add_filter( 'should_load_separate_core_block_assets', '__return_true' ); + add_filter( 'wp_should_load_block_assets_on_demand', '__return_true' ); /* * Remove the Customizer's Menus panel when block theme is active. diff --git a/tests/phpunit/tests/blocks/register.php b/tests/phpunit/tests/blocks/register.php index 7e0c391e1f226..8a5558fd3f4cf 100644 --- a/tests/phpunit/tests/blocks/register.php +++ b/tests/phpunit/tests/blocks/register.php @@ -571,6 +571,8 @@ public function test_wrong_array_index_do_not_register_block_style_handle() { * @param string $block_json_path Path to the `block.json` file, relative to ABSPATH. * @param string $style_field Either 'style' or 'editorStyle'. * @param string|bool $expected_path Expected path of registered stylesheet, relative to ABSPATH. + * + * @expectedDeprecated should_load_separate_core_block_assets */ public function test_register_block_style_handle_uses_correct_core_stylesheet( $block_json_path, $style_field, $expected_path ) { $metadata_file = ABSPATH . $block_json_path; diff --git a/tests/phpunit/tests/blocks/registerCoreBlockStyleHandles.php b/tests/phpunit/tests/blocks/registerCoreBlockStyleHandles.php index 6f710cab18841..a69fa892884ca 100644 --- a/tests/phpunit/tests/blocks/registerCoreBlockStyleHandles.php +++ b/tests/phpunit/tests/blocks/registerCoreBlockStyleHandles.php @@ -80,6 +80,8 @@ public function test_wp_should_load_separate_core_block_assets_false( $name, $sc * * @param string $name The block name. * @param array $schema The block's schema. + * + * @expectedDeprecated should_load_separate_core_block_assets */ public function test_wp_should_load_separate_core_block_assets_true( $name, $schema ) { add_filter( 'should_load_separate_core_block_assets', '__return_true' ); @@ -111,6 +113,8 @@ public function test_wp_should_load_separate_core_block_assets_true( $name, $sch * @dataProvider data_block_data * * @param string $name The block name. + * + * @expectedDeprecated should_load_separate_core_block_assets */ public function test_wp_should_load_separate_core_block_assets_current_theme_supports( $name ) { add_filter( 'should_load_separate_core_block_assets', '__return_true' ); @@ -138,6 +142,8 @@ public function test_wp_should_load_separate_core_block_assets_current_theme_sup * @dataProvider data_block_data * * @param string $name The block name. + * + * @expectedDeprecated should_load_separate_core_block_assets */ public function test_register_core_block_style_handles_should_load_rtl_stylesheets_for_rtl_text_direction( $name ) { global $wp_locale; diff --git a/tests/phpunit/tests/dependencies/styles.php b/tests/phpunit/tests/dependencies/styles.php index 9cb6283c488d5..bdd9428cc25fc 100644 --- a/tests/phpunit/tests/dependencies/styles.php +++ b/tests/phpunit/tests/dependencies/styles.php @@ -490,6 +490,8 @@ public function test_block_styles_for_viewing_with_theme_support() { * @ticket 50263 * * @covers ::wp_default_styles + * + * @expectedDeprecated should_load_separate_core_block_assets */ public function test_block_styles_for_viewing_without_split_styles() { add_filter( 'should_load_separate_core_block_assets', '__return_false' ); @@ -507,6 +509,8 @@ public function test_block_styles_for_viewing_without_split_styles() { * @ticket 50263 * * @covers ::wp_default_styles + * + * @expectedDeprecated should_load_separate_core_block_assets */ public function test_block_styles_for_viewing_with_split_styles() { add_filter( 'should_load_separate_core_block_assets', '__return_true' ); diff --git a/tests/phpunit/tests/theme.php b/tests/phpunit/tests/theme.php index 48576672b9a26..aa5c3131caa6a 100644 --- a/tests/phpunit/tests/theme.php +++ b/tests/phpunit/tests/theme.php @@ -864,6 +864,9 @@ public function data_block_theme_has_default_support() { * * @covers ::_add_default_theme_supports * @covers ::wp_should_load_separate_core_block_assets + * + * @expectedDeprecated wp_should_load_separate_core_block_assets + * @expectedDeprecated should_load_separate_core_block_assets */ public function test_block_theme_should_load_separate_core_block_assets_by_default() { $this->helper_requires_block_theme(); diff --git a/tests/phpunit/tests/theme/wpAddGlobalStylesForBlocks.php b/tests/phpunit/tests/theme/wpAddGlobalStylesForBlocks.php index 7d34e8d2a6b33..c97e772b500e2 100644 --- a/tests/phpunit/tests/theme/wpAddGlobalStylesForBlocks.php +++ b/tests/phpunit/tests/theme/wpAddGlobalStylesForBlocks.php @@ -78,6 +78,8 @@ public function test_third_party_blocks_inline_styles_get_registered_to_global_s /** * @ticket 56915 * @ticket 61165 + * + * @expectedDeprecated should_load_separate_core_block_assets */ public function test_third_party_blocks_inline_styles_get_registered_to_global_styles_when_per_block() { $this->set_up_third_party_block(); @@ -103,6 +105,8 @@ public function test_third_party_blocks_inline_styles_get_registered_to_global_s /** * @ticket 56915 * @ticket 61165 + * + * @expectedDeprecated should_load_separate_core_block_assets */ public function test_third_party_blocks_inline_styles_get_rendered_when_per_block() { $this->set_up_third_party_block(); @@ -153,6 +157,8 @@ public function test_blocks_inline_styles_get_rendered() { /** * @ticket 57868 * @ticket 61165 + * + * @expectedDeprecated should_load_separate_core_block_assets */ public function test_third_party_blocks_inline_styles_for_elements_get_rendered_when_per_block() { $this->set_up_third_party_block();