Block Variations: Add PHP version of wp.blocks.registerBlockVariation

[mateuswetah]

What problem does this address?

Part of #41236.

This has been requested here and here. I figure it will be handy for many reasons.

For example, I have a plugin that dynamically creates several CPTs. I would like to register Query Loop block variations for each CPT on the serve side and that would be easier if this was available.

What is your proposed solution?

Nothing fancy, just a register_block_variation, if possible ;)

[gziolo]

@mateuswetah, thank you for sharing the idea. It is possible to inject a block variation using filters as of today because variations can be defined in PHP during block registration:

https://github.com/WordPress/wordpress-develop/blob/3b4132d6c096a8a17fa52b9e00a201985a243406/src/wp-includes/class-wp-block-type.php#L112-L118

You could use register_block_type_args to define or extend block variations.

I agree that we should consider introducing a higher-level API like register_block_variation to align with other utilities that exist today like register_block_style or register_block_script_handle. It's something that we should seek feedback about from more folks before proceeding with implementation.

[mateuswetah]

Hey thanks for the pro tip @gziolo! I'll try that path in any case while you folks get more feedback.

[lmisch]

Definitely a +1 :)

[chrillep]

+1 full feature parity is the goal right? ❤️

[chrillep]

@mateuswetah, thank you for sharing the idea. It is possible to inject a block variation using filters as of today because variations can be defined in PHP during block registration:

https://github.com/WordPress/wordpress-develop/blob/3b4132d6c096a8a17fa52b9e00a201985a243406/src/wp-includes/class-wp-block-type.php#L112-L118

You could use register_block_type_args to define or extend block variations.

I agree that we should consider introducing a higher-level API like register_block_variation to align with other utilities that exist today like register_block_style or register_block_script_handle. It's something that we should seek feedback about from more folks before proceeding with implementation.

@gziolo could you please supply a code example using this on a core block?

is https://wordpress.stackexchange.com/a/413463 a good example?

<?php
function extended_query_excerpt_block_args($args) {
    $args['render_callback'] = 'render_block_core_post_excerpt';
    $args['attributes']['variantType'] = [
        'type' => 'string'
    ];
    $args['variations'] = [
        [
            'name' => 'three-lines-excerpt',
            'title' => 'Three lines excerpt',
            'attributes' => [
                'variantType' => 'three-lines-excerpt'
            ],
        ]
    ];
    return $args;
}

function register_variation($args, $block_type) {
    return match ($block_type) {
        'core/post-excerpt' => extended_query_excerpt_block_args($args),
        default => $args
    };
}

add_filter( 'register_block_type_args', 'register_variation', 10, 2 );

[gziolo]

could you please supply a code example using this on a core block?

The example you shared will work fine in the case when the block is registered on the server and you can tap into the registration phase. I mentioned it before, that probably replicating register_block_style would fit best here:

https://github.com/WordPress/wordpress-develop/blob/b315d4ec015572f17848cad3960b20b7cd4da0f1/src/wp-includes/blocks.php#L1619-L1621

https://github.com/WordPress/wordpress-develop/blob/trunk/src/wp-includes/class-wp-block-styles-registry.php

This is how block styles gets passed to the editor:

https://github.com/WordPress/wordpress-develop/blob/b315d4ec015572f17848cad3960b20b7cd4da0f1/src/wp-includes/script-loader.php#L2709-L2735

In practice, for server-side registered blocks you don't need to use to call any JavaScript code. So calling wp.blocks.registerBlockStyle( \'%s\,' %s ) would also be a fallback for client-side-only blocks.

[joemcgill]

Now that support for registering a callback for deferred loading of block variations has landed in WP core Trac #59969 it would be great to add a proper API for modifying variations on the server.

The way I would expect this to work is that public functions for adding/removing block variations would be wrappers for new methods on the WP_Block_Type object that first make sure that the WP_Block_Type::variation_callback() has been run prior to making any changes to the stored WP_Block_Type::variations property, changing the array of variations, and then setting the modified array back to the variations property. This should also avoid running the get_block_type_variations filter hook in WP_Block_Type::get_variations() so that filtered values don't end up getting stored back to the property but only effect variations once they are retrieved.

Unsure if this can be implemented in this repo or if some changes need to happen in core, but it would be great to get some testing of this through Gutenberg if possible.

[mateuswetah]

Considering the mentioned here: https://make.wordpress.org/core/2024/02/29/performance-improvements-for-registering-block-variations-with-callbacks/

And the comment from @joemcgill, I'm unsure if we should close this or not. After all it seems that Block variations can be defined server side, they are just missing an API that looks the same as the JS side is.

[bacoords]

After all it seems that Block variations can be defined server side, they are just missing an API that looks the same as the JS side is.

I would note that having a clear way to register block variations server side would be a major win for new developers/theme developers and would help raise awareness of the feature. Plus it would be a lot less error prone than manually writing the filter.

That said, if having an abstracted PHP function isn't going to happen, the alternative would be to at least include basic instructions on how to register them server side in the documentation: https://developer.wordpress.org/block-editor/reference-guides/block-api/block-variations/ If that sounds reasonable to others I could open a separate ticket for the documentation update.

[mateuswetah]

+1 for the documentation anyways, I discovered this possibility via blog news 😅