wp_register_block_metadata_collection() │ WP 6.7.0

Registers a collection of block metadata from a shared PHP manifest.

WordPress retrieves the metadata for every block in the collection from a single file. This reduces filesystem access and eliminates the need to parse each block.json file separately.

The manifest must return an associative array. Each item key contains the block identifier without its namespace and must match the block directory name.

No Hooks.

Returns

null.

• null — Does not return anything. The result of the internal registration method is not passed to the calling code.

Usage

wp_register_block_metadata_collection( $path, $manifest );

$path(string) (required)

Absolute path to the base directory containing the collection's block directories.

The path is normalized and its trailing slash is removed.

You cannot specify the root directories of wp-includes, plugins, must-use plugins, or themes, nor their parent directories. You can specify a subdirectory of a specific plugin or theme.

$manifest(string) (required)

Absolute path to the PHP manifest file.

The file must return an array in the format block_identifier => metadata. The identifier is specified without a namespace and must match the block directory name.

If the file does not exist, the collection is not registered and WordPress generates an incorrect-usage notice.

Examples

#1 Registering a collection and individual blocks

You can create the blocks-manifest.php file with the command:

wp-scripts build-blocks-manifest

By default, the command collects metadata from the build directory and creates the build/blocks-manifest.php file.

function my_plugin_register_blocks() {
	$build_path = __DIR__ . '/build';

	wp_register_block_metadata_collection(
		$build_path,
		$build_path . '/blocks-manifest.php'
	);

	register_block_type( $build_path . '/notice' );

	register_block_type(
		$build_path . '/button',
		[
			'render_callback' => 'my_plugin_render_button_block',
		]
	);
}

add_action( 'init', 'my_plugin_register_blocks' );

Example directory structure:

build/
├── blocks-manifest.php
├── button/
│   └── block.json
└── notice/
	└── block.json

The manifest has the following structure:

<?php

return [
	'button' => [
		'name'  => 'my-plugin/button',
		'title' => 'Button',
	],
	'notice' => [
		'name'  => 'my-plugin/notice',
		'title' => 'Notice',
	],
];