Background

In WordPress 5.8, the APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. for registering blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. variations was introduced, bringing new capabilities to developers. However, it soon became evident that generating these variations had a non-trivial performance cost, particularly when used for template-part and navigation-link in WordPress 5.9 and post-terms in WordPress 6.1.

The coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. of this issue was that these variations were being generated on every page load due to their registration using the init hook. This was inefficient, as the variations were only needed in the editor or for returning block data in the REST APIREST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) https://developer.wordpress.org/rest-api/.. This redundancy in loading led to unnecessary performance overhead, underscoring the need for a more streamlined approach.

What is changed

In WordPress 6.5, we’ve introduced $variation_callback as a new attribute in WP_Block_Type. This feature allows developers to register variation-building functions as callbacks rather than building variations before registration. With this approach, variations are constructed from this callback only when they are accessed for the first time. 

Consequently, the WP_Block_Type::get_variations() method was introduced as the primary means to access variations. This method skillfully checks for a callback in variation_callback and triggers the callback, but only during the first access of the variations. This efficient approach ensures that the callback is executed just once, optimizing performance by avoiding redundant processing on subsequent accesses. Additionally, this strategy aids in lazy loading, as variations no longer need to be loaded during registration.

Moreover, it integrates the get_block_type_variations filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output., which provides a versatile mechanism for developers to modify the resulting variations. These enhancements reflect WordPress’s ongoing commitment to improving its developer-centric features and maintaining compatibility with existing functionalities.
In WordPress 6.5, a significant alteration is made to WP_Block_Type::$variations. The notable change involved transitioning the visibility of variations from public to private. This modification was specifically designed to necessitate the use of the PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher magic __get method for accessing variations only via WP_Block_Type::get_variations().

Please note that the modifications to WP_Block_Type::$variations may introduce certain limitations that require developer attention. These are detailed in the “Developer Action” section below.

Lazy loading variations using variation_callback

To facilitate the lazy loading of variations, we can replace the traditional method of loading variations with a callback. This approach is exemplified in the case of GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ PR #56952, which is aimed at enhancing performance.

Previously, template-part variations were loaded as follows:

register_block_type_from_metadata(
    __DIR__ . '/template-part',
    array(
        'render_callback'    => 'render_block_core_template_part',
        'variations'         => build_template_part_block_variations(),
    )
);

To optimize this, we have transitioned to using a variation_callback:

register_block_type_from_metadata(
    __DIR__ . '/template-part',
    array(
        'render_callback'    => 'render_block_core_template_part',
        'variation_callback' => 'build_template_part_block_variations',
    )
);

It’s important to note that if both variations and variation_callback are defined, like in the following example:

register_block_type_from_metadata(
    'block-name',
    array(
        'variations'         => array( 'test-variation' => array( 'test-variations' ) ),
        'variation_callback' => 'get_test_variations',
    )
);

In this scenario, the variations array takes precedence, and the variation_callback will not be called.

Developer action required

With the addition of variations to the existing magic function framework in WP_Block_Type, a significant limitation emerges: the inability to modify variations by reference directly. This change impacts how variations were traditionally updated.

Consider these examples of updating variations by reference, which will no longer function as expected in WordPress 6.5:

$block_type->variations[] = array( 'test' => array( 'test' ) );
// or
$block_type->variations['example1'] = array( 'test' );

To overcome this limitation in WordPress 6.5, a workaround involving a temporary variable can be used. Here’s how you can modify the temporary variable and then reassign it back to $block_type->variations:

$variations = $block_type->variations;$variations[] = array( 'test' => array( 'test' ) );
$block_type->variations = $variations;
// Similarly$variations = $block_type->variations;
$variations['example1'] = array( 'test' );$block_type->variations = $variations;

Alternatively, to align with the latest updates and best practices in WordPress, you might consider using the get_block_type_variations filter (reference link).

Utilizing the get_block_type_variations filter for enhanced variation management

The introduction of the get_block_type_variations filter in WordPress 6.5 allows for the manipulation and customization of the variations array, providing greater flexibility in handling block variations.

Here’s an implementation example of the get_block_type_variations filter:

function modify_block_type_variations( $variations, $block_type ) {
    // Example: Add a new variation
    if ( 'block-name' === $block_type->name ) {
        $variations[] = array(
            'name'  => 'new-variation',
            'title' => __( 'New Variation', 'textdomain' ),
            // Other variation properties...
        );
    }

    return $variations;
}
add_filter( 'get_block_type_variations', 'modify_block_type_variations', 10, 2 );

In this example, the modify_block_type_variations function is hooked to the get_block_type_variations filter. It checks if the block type is ‘block-name‘ and then adds a new variation to the variations array. This function then returns the modified variations array.

By leveraging this filter, developers can dynamically adjust the variations according to specific requirements or conditions.

Please refer to #59969 for additional details on these changes.

Props to @adamsilverstein, @westonruter, @joemcgill, and @leonnugraha for reviewing this post.

#6-5, #block-api, #dev-notes, #dev-notes-6-5