Block API: Add new utility to register block types from metadata in PHP

[gziolo]

Description

Follow up for #19786 and #20717 where we started using block.json file in PHP to register block types.

This PR tries to simplify the process by removing code duplication for the same tasks that need happen for every block.

API is based on my previous discussion with @azaozz. I hightlighed the most important parts below:

Perhaps the abstracted function can have __file__ as optional param and "calculate" the proper path? Maybe something like:

function wp_get_block_metadata( $file, $path = null ) {
    if ( empty( $path ) ) {
        $path = ABSPATH . WPINC . '/blocks';
    }

    $file = trailingslashit( $path ) . $file;

    if ( file_exists( $file ) {
        return json_decode( file_get_contents( $file ), true );
    }

    return false;
}

I followed your proposal for params. I don't know what patterns are used in other places, but an alternative approach could be prepending ABSPATH . WPINC . '/blocks' in the case where the $file is not absolute. You could also omit the name of the file and default to block.json:

$metadata = wp_get_block_metadata( 'shortcode' );
// becomes ABSPATH . WPINC . '/blocks/shortcode/block.json'
$metadata = wp_get_block_metadata( __DIR__ );
// becomes __DIR__ . '/block.json'

As the file name is known, in core it will only need the (last) dir name, i.e. the block name. Then it can do: $file = ABSPATH . WPINC . "/blocks/{$file}"; to get the default location in core, and plugins will be able to use __DIR__.

Then perhaps it will look like register_block_type_from_metadata( $path, $args = null ) { ... where $path will be __DIR__ when used from plugins and "block name" when used in core.

API proposed

/**
 * Registers a block type from metadata stored in the `block.json` file.
 *
 * @param string $path Path to the folder where the `block.json` file is located.
 *                     Alternatively it's possible to provide only the name of the
 *                     last folder for blocks located in the WordPress core.
 * @param array  $args {
 *     Optional. Array of block type arguments. Any arguments may be defined, however the
 *     ones described below are supported by default. Default empty array.
 *
 *     @type callable $render_callback Callback used to render blocks of this block type.
 * }
 * @return WP_Block_Type|false The registered block type on success, or false on failure.
 */
function register_block_type_from_metadata( $path, $args = array() );

Example

register_block_type_from_metadata(
	__DIR__ . '/shortcode',
	array(
		'render_callback' => 'render_block_core_shortcode',
	)
);

How has this been tested?

• npm run test-php && npm run test-unit-php-multisite
• npm run test-e2e

I also manually tested that the experimental Edit Site still works and all blocks are registered on the server.

Types of changes

New API method introduced and core blocks are refactored to use it.

Checklist:

• My code is tested.
• My code follows the WordPress code style.
• My code has proper inline documentation.
• I've included developer documentation if appropriate.

[github-actions]

Size Change: 0 B

Total Size: 864 kB

ℹ️ View Unchanged

Filename	Size	Change
build/a11y/index.js	1.01 kB	0 B
build/annotations/index.js	3.43 kB	0 B
build/api-fetch/index.js	3.39 kB	0 B
build/autop/index.js	2.58 kB	0 B
build/blob/index.js	620 B	0 B
build/block-directory/index.js	6.02 kB	0 B
build/block-directory/style-rtl.css	760 B	0 B
build/block-directory/style.css	760 B	0 B
build/block-editor/index.js	105 kB	0 B
build/block-editor/style-rtl.css	10.7 kB	0 B
build/block-editor/style.css	10.7 kB	0 B
build/block-library/editor-rtl.css	7.23 kB	0 B
build/block-library/editor.css	7.24 kB	0 B
build/block-library/index.js	116 kB	0 B
build/block-library/style-rtl.css	7.38 kB	0 B
build/block-library/style.css	7.39 kB	0 B
build/block-library/theme-rtl.css	669 B	0 B
build/block-library/theme.css	671 B	0 B
build/block-serialization-default-parser/index.js	1.65 kB	0 B
build/block-serialization-spec-parser/index.js	3.1 kB	0 B
build/blocks/index.js	57.7 kB	0 B
build/components/index.js	191 kB	0 B
build/components/style-rtl.css	15.5 kB	0 B
build/components/style.css	15.5 kB	0 B
build/compose/index.js	5.75 kB	0 B
build/core-data/index.js	10.6 kB	0 B
build/data-controls/index.js	1.03 kB	0 B
build/data/index.js	8.22 kB	0 B
build/date/index.js	5.36 kB	0 B
build/deprecated/index.js	772 B	0 B
build/dom-ready/index.js	569 B	0 B
build/dom/index.js	3.06 kB	0 B
build/edit-post/index.js	91.3 kB	0 B
build/edit-post/style-rtl.css	8.64 kB	0 B
build/edit-post/style.css	8.64 kB	0 B
build/edit-site/index.js	4.64 kB	0 B
build/edit-site/style-rtl.css	2.48 kB	0 B
build/edit-site/style.css	2.48 kB	0 B
build/edit-widgets/index.js	4.44 kB	0 B
build/edit-widgets/style-rtl.css	2.58 kB	0 B
build/edit-widgets/style.css	2.58 kB	0 B
build/editor/editor-styles-rtl.css	381 B	0 B
build/editor/editor-styles.css	382 B	0 B
build/editor/index.js	43.8 kB	0 B
build/editor/style-rtl.css	3.97 kB	0 B
build/editor/style.css	3.96 kB	0 B
build/element/index.js	4.45 kB	0 B
build/escape-html/index.js	734 B	0 B
build/format-library/index.js	7.09 kB	0 B
build/format-library/style-rtl.css	502 B	0 B
build/format-library/style.css	502 B	0 B
build/hooks/index.js	1.92 kB	0 B
build/html-entities/index.js	622 B	0 B
build/i18n/index.js	3.49 kB	0 B
build/is-shallow-equal/index.js	710 B	0 B
build/keyboard-shortcuts/index.js	2.3 kB	0 B
build/keycodes/index.js	1.68 kB	0 B
build/list-reusable-blocks/index.js	2.99 kB	0 B
build/list-reusable-blocks/style-rtl.css	226 B	0 B
build/list-reusable-blocks/style.css	226 B	0 B
build/media-utils/index.js	4.85 kB	0 B
build/notices/index.js	1.57 kB	0 B
build/nux/index.js	3.01 kB	0 B
build/nux/style-rtl.css	616 B	0 B
build/nux/style.css	613 B	0 B
build/plugins/index.js	2.54 kB	0 B
build/primitives/index.js	1.49 kB	0 B
build/priority-queue/index.js	780 B	0 B
build/redux-routine/index.js	2.84 kB	0 B
build/rich-text/index.js	14.3 kB	0 B
build/server-side-render/index.js	2.55 kB	0 B
build/shortcode/index.js	1.7 kB	0 B
build/token-list/index.js	1.27 kB	0 B
build/url/index.js	4.01 kB	0 B
build/viewport/index.js	1.61 kB	0 B
build/warning/index.js	1.14 kB	0 B
build/wordcount/index.js	1.18 kB	0 B

_{compressed-size-action}

[gziolo]

I made PHPUnit tests pass, and all jobs on Travis. I think it's ready for the final check.

[aduth]

Some general thoughts which occur to me, mostly a brain dump and none of which are particularly blocking:

• I'm wondering how this relates or is expected to interoperate with other plugin filesystem functions. Looking at ones like plugin_dir_path, which often receive __FILE__ of the plugin file, then it's up to the plugin author to concatenate that to whichever file they're targeting. This feels a bit different in that it absorbs most of that responsibility, and assumes that the metadata will always be found at block.json.
• If and where we should document this sooner than later, or at least how best we can seek feedback in the early stages of the availability of this function.

[azaozz]

which often receive FILE of the plugin file, then it's up to the plugin author to concatenate that to whichever file they're targeting.

Yeah, that was the earlier idea with a separate function to calculate the path. But it is quite straightforward to do, so opted for not adding a separate helper function. Using either plugin_dir_path() or __DIR__ works well. Currently register_block_type_from_metadata() resembles wp_enqueue_script() rather than plugin_dir_path().

assumes that the metadata will always be found at block.json.

Was thinking that is expected, like having index.js and index.css? Are there any reasons to support random file names?

[gziolo]

If and where we should document this sooner than later, or at least how best we can seek feedback in the early stages of the availability of this function

My first idea was to omit the documentation part until we reach WordPress 5.5 release cycle to avoid all the confusion for those who browse https://developer.wordpress.org/block-editor/ and can't use this new block registration utility with WordPress core. We also miss support for two features proposed in Block Registration RFC:

• assets integration
• internatiolization

I think it might be a good idea to add a section in this RFC document as a follow-up (plus refresh the document in general) that would describe how this is going to work moving forward. If you agree I'm happy to open a follow-up PR.

assumes that the metadata will always be found at block.json.

Was thinking that is expected, like having index.js and index.css? Are there any reasons to support random file names?

I don't think we strictly require index.js – when using wp-scripts build it defaults to src/index.js but you can change it with CLI options. I wouldn't be opposed to allowing some custom file names as well, but I also opted for the simplest approach in the context of the Block Directory where block.json is mandatory (https://github.com/WordPress/wporg-plugin-guidelines/blob/block-guidelines/blocks.md#4-block-plugins-must-include-a-blockjson-file). Technically speaking, when you build a plugin with multiple blocks you might want to have the freedom to pick any name so 🤷‍♂

[aduth]

assumes that the metadata will always be found at block.json.

Was thinking that is expected, like having index.js and index.css? Are there any reasons to support random file names?

Not necessarily, no. It just struck me as rather opinionated in how we're expecting a plugin of blocks to be structured. As an example, perhaps one might feel compelled to have a folder of blocks instead of a folder of folders of blocks (i.e. blocks/paragraph.php, blocks/paragraph.json, blocks/heading.php, blocks/heading.json). I don't know that I would classify these as "random". They're certainly outside the scope of what we're defining as to be the supported usage. Which, to be clear, can be perfectly fine (to call this usage "unsupported")!

[gziolo]

Let's proceed here and work on documentation in a follow-up task. I will also open a new issue in trac with a proposal to include it in WordPress core. Thank you for all feedback shared.

[gziolo]

I opened #21501 where I document this new method in RFC document. Next step, propose it to WordPress core.