Registers a block metadata collection.
Description
This method allows registering a collection of block metadata from a single manifest file, improving performance for large sets of blocks.
The manifest file should be a PHP file that returns an associative array, where the keys are the block identifiers (without their namespace) and the values are the corresponding block metadata arrays. The block identifiers must match the parent directory name for the respective block.json file.
Example manifest file structure:
return array(
'example-block' => array(
'title' => 'Example Block',
'category' => 'widgets',
'icon' => 'smiley',
// ... other block metadata
),
'another-block' => array(
'title' => 'Another Block',
'category' => 'formatting',
'icon' => 'star-filled',
// ... other block metadata
),
// ... more block metadata entries
);Parameters
$pathstringrequired- The absolute base path for the collection ( e.g., WP_PLUGIN_DIR .
'/my-plugin/blocks/'). $manifeststringrequired- The absolute path to the manifest file containing the metadata collection.
Source
public static function register_collection( $path, $manifest ) {
$path = rtrim( wp_normalize_path( $path ), '/' );
$collection_roots = self::get_default_collection_roots();
/**
* Filters the root directory paths for block metadata collections.
*
* Any block metadata collection that is registered must not use any of these paths, or any parent directory
* path of them. Most commonly, block metadata collections should reside within one of these paths, though in
* some scenarios they may also reside in entirely different directories (e.g. in case of symlinked plugins).
*
* Example:
* * It is allowed to register a collection with path `WP_PLUGIN_DIR . '/my-plugin'`.
* * It is not allowed to register a collection with path `WP_PLUGIN_DIR`.
* * It is not allowed to register a collection with path `dirname( WP_PLUGIN_DIR )`.
*
* The default list encompasses the `wp-includes` directory, as well as the root directories for plugins,
* must-use plugins, and themes. This filter can be used to expand the list, e.g. to custom directories that
* contain symlinked plugins, so that these root directories cannot be used themselves for a block metadata
* collection either.
*
* @since 6.7.2
*
* @param string[] $collection_roots List of allowed metadata collection root paths.
*/
$collection_roots = apply_filters( 'wp_allowed_block_metadata_collection_roots', $collection_roots );
$collection_roots = array_unique(
array_map(
static function ( $allowed_root ) {
return rtrim( wp_normalize_path( $allowed_root ), '/' );
},
$collection_roots
)
);
// Check if the path is valid:
if ( ! self::is_valid_collection_path( $path, $collection_roots ) ) {
_doing_it_wrong(
__METHOD__,
sprintf(
/* translators: %s: list of allowed collection roots */
__( 'Block metadata collections cannot be registered as one of the following directories or their parent directories: %s' ),
esc_html( implode( wp_get_list_item_separator(), $collection_roots ) )
),
'6.7.2'
);
return false;
}
if ( ! file_exists( $manifest ) ) {
_doing_it_wrong(
__METHOD__,
__( 'The specified manifest file does not exist.' ),
'6.7.0'
);
return false;
}
self::$collections[ $path ] = array(
'manifest' => $manifest,
'metadata' => null,
);
return true;
}
Hooks
- apply_filters( ‘wp_allowed_block_metadata_collection_roots’,
string[] $collection_roots ) Filters the root directory paths for block metadata collections.
Changelog
| Version | Description |
|---|---|
| 6.7.0 | Introduced. |
User Contributed Notes
You must log in before being able to contribute a note or feedback.