Editor: Extend `register_block_type` to accept the path file or folder with `block.json`

[gziolo]

The idea comes from @matveb. Rather than using two distinct methods to register block types in WordPress core, let's make register_block_type the canonical method to deal with all use cases. In practice, the patch proposed extends its usage to work as a proxy to register_block_type_from_metadata. It should remove some confusion that we observed and let us be more explicit what's the latest recommendation.

From now on, we should always promote combining block.json file with register_block_type call:

register_block_type( __DIR__ );

In the example above, it will register the block from the metadata stored in block.json that is located in the same folder as the PHP script that calls the method.

[gziolo]

I tested whether the name of the block namespace/slug could potentially get detected by file_exists call when the same folder exists. In practice, it turns out it is impossible because file_exists expects a full path, test scenario used:

$this->assertTrue( file_exists( __DIR__ . '/my/plugin' ) );
$this->assertFalse( file_exists( './my/plugin' ) );
$this->assertFalse( file_exists( 'my/plugin' ) );

[gziolo]

In 50927:

Editor: Extend register_block_type to accept the path file or folder with block.json

Rather than using two distinct methods to register block types in WordPress core, let's make register_block_type the canonical method to deal with all use cases. In practice, the patch proposed extends its usage to work as a proxy to register_block_type_from_metadata. It should remove some confusion that we observed and let us be more explicit what's the latest recommendation.

Props matveb, mcsf.
Fixes #53233.

[gziolo]

In 50928:

Docs: Include @since in register_block_type definition

See #53233.

[Clorith]

I'm totally on board with the idea of having one canonical function for registering blocks, but I'm a bit worried about the implementation and direction as it stands.

WordPress 5.7 had changes which made a lot of folks switch from register_block_type to register_block_type_from_metadata because of new requirements in registering attributes, which non-serverside blocks often did not declare to PHP, as it wasn't required. Making this swap made the transition less troublesome than having to re-declare everything in multiple locations.

The patch committed in [50927] maintains backwards compatibility by checking if it's a legitimate path provided, or a string (which should be interpreted as the block slug), but given that this is becoming canonical, it is not unreasonable to presume that register_block_type_from_metadata will be getting a __doing_it_wrong() when called directly in the future, reversing the current need folks had just one release back to switch to this function.

It's also not possible for folks to future, or backwards proof their code, since the file path can only be provided in 5.8 or above, meaning they'd (potentially) end up with three implementations depending on which WP versions they support.

I also fear this hurts an already strained developer relationship where there's murmur of too many breaking changes between each core release due to the block editor.

[gziolo]

@Clorith, let me clarify some decisions made so far and the rationale behind them.

register_block_type_from_metadata is here to stay for backward compatibility for the time being. It's now used internally by register_block_type so both approaches work just fine. The latter is just shorter and it will simplify documentation efforts. The goal now is to promote usage of register_block_type together with block.json file in the WordPress context. I'm working on the dev note that is going to highlight the benefits that block following that approach will get now and how we see it evolving in the future. We could deprecate register_block_type_from_metadata but at this stage, it will only create friction for existing blocks that already opted for using block.json as you correctly identified it. I guess we can do it in the future but I would rather focus on promoting good practices in the official learning materials.

In the Gutenberg plugin, there is registerBlockTypeFromMetadata function that is already deprecated but we plan to remove it in a few weeks, and it existed temporarily for use cases outside of WordPress core - mostly for bridging handling in the native mobile apps.

I share your sentiment that the process isn't ideal, but it was a long process to implement all features necessary for block registration using block.json file that will open us new ways to optimize the rendering of the block in the editor and on the frontend - conditional loading of styles for rendered blocks coming in WP 5.8 is one of the best examples so far.