register_block_type_from_metadata( string $file_or_folder, array $args = array() ): WP_Block_Type|false

Compatibility

Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.

Parameters

$file_or_folderstring

Path to the JSON file with metadata definition for the block or path to the folder where the block.json file is located.
If providing the path to a JSON file, the filename must end with block.json.

$argsarrayoptional

Array of block type arguments. Accepts any public property of WP_Block_Type. See WP_Block_Type::__construct() for information on accepted arguments. Default empty array.Default: array()

Return value

WP_Block_Type|false

The registered block type on success, or false on failure.

Performance profile

How much work a call to register_block_type_from_metadata() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.

Cost class

Trivial

Touches nothing outside its own arguments.

Scaling

Constant

No loop in the body: the same number of instructions runs whatever you pass in.

Instructions

4

Executed per call on PHP 8.5. The body compiles to 390.

Plugin surface

2 hooks

Third-party callbacks on 'block_type_metadata', 'block_type_metadata_settings' run inside this call, and their cost is not bounded by anything here.

Called by

50

50 places in core call this, so the cost is paid more often than your own code shows.

What it touches

• hookthird-party callbacksapply_filters()called directly

Further down the call graph this can also reach option, cache, serialize, query and transient. Those are the worst case, several calls deep and usually down an error path, not what a normal call pays.

What one call costs · 1 distinct outcome

One number would be a lie: the work depends on which branch runs. These are every distinct cost register_block_type_from_metadata() can have, taken from its control-flow graph on PHP 8.5.

Hooks and filters fired · 2

2 hooks fire while register_block_type_from_metadata() runs, in this order:

1. 1
   apply_filters( block_type_metadata )filterline 559 (+39 into the body)

   Filters the metadata provided for registering a block type.

2. 2
   apply_filters( block_type_metadata_settings )filterline 814 (+294 into the body)

   Filters the settings determined from the block type metadata.

Uses · 19

• wp_normalize_path()Normalizes a filesystem path.
• str_ends_with()Polyfill for `str_ends_with()` function added in PHP 8.0.
• trailingslashit()Appends a trailing slash.
• str_starts_with()Polyfill for `str_starts_with()` function added in PHP 8.0.
• wp_json_file_decode()Reads and decodes a JSON file.
• apply_filters()Calls the callback functions that have been added to a filter hook.
• current_theme_supports()Checks a theme's support for a given feature.
• wp_should_load_separate_core_block_assets()Checks whether separate styles should be loaded for core blocks.
• get_block_metadata_i18n_schema()Gets i18n schema for block's metadata read from `block.json` file.
• translate_settings_using_i18n_schema()Translates the provided settings value using its i18n schema.
• remove_block_asset_path_prefix()Removes the block asset's path prefix if provided.
• register_block_script_handle()Finds a script handle for the selected block metadata field.

Used by · 50

• register_block_core_accordion()Registers the `core/accordion` block on server.
• register_block_core_accordion_item()Registers the `core/accordion-item` block on server.
• register_block_core_archives()Register archives block.
• register_block_core_avatar()Registers the `core/avatar` block on the server.
• register_block_core_block()Registers the `core/block` block.
• register_block_core_breadcrumbs()Registers the `core/breadcrumbs` block on the server.
• register_block_core_button()Registers the `core/button` block on server.
• register_block_core_calendar()Registers the `core/calendar` block on server.
• register_block_core_categories()Registers the `core/categories` block on server.
• register_block_core_comment_author_name()Registers the `core/comment-author-name` block on the server.
• register_block_core_comment_content()Registers the `core/comment-content` block on the server.
• register_block_core_comment_date()Registers the `core/comment-date` block on the server.

Source code

View on Trac ↗View on GitHub ↗

520function register_block_type_from_metadata( $file_or_folder, $args = array() ) {521	/*522	 * Get an array of metadata from a PHP file.523	 * This improves performance for core blocks as it's only necessary to read a single PHP file524	 * instead of reading a JSON file per-block, and then decoding from JSON to PHP.525	 * Using a static variable ensures that the metadata is only read once per request.526	 */527 528	$file_or_folder = wp_normalize_path( $file_or_folder );529 530	$metadata_file = ( ! str_ends_with( $file_or_folder, 'block.json' ) ) ?531		trailingslashit( $file_or_folder ) . 'block.json' :532		$file_or_folder;533 534	$is_core_block        = str_starts_with( $file_or_folder, wp_normalize_path( ABSPATH . WPINC ) );535	$metadata_file_exists = $is_core_block || file_exists( $metadata_file );536	$registry_metadata    = WP_Block_Metadata_Registry::get_metadata( $file_or_folder );537 538	if ( $registry_metadata ) {539		$metadata = $registry_metadata;540	} elseif ( $metadata_file_exists ) {541		$metadata = wp_json_file_decode( $metadata_file, array( 'associative' => true ) );542	} else {543		$metadata = array();544	}545 546	if ( ! is_array( $metadata ) || ( empty( $metadata['name'] ) && empty( $args['name'] ) ) ) {547		return false;548	}549 550	$metadata['file'] = $metadata_file_exists ? wp_normalize_path( realpath( $metadata_file ) ) : null;551 552	/**553	 * Filters the metadata provided for registering a block type.554	 *555	 * @since 5.7.0556	 *557	 * @param array $metadata Metadata for registering a block type.558	 */559	$metadata = apply_filters( 'block_type_metadata', $metadata );560 561	// Add `style` and `editor_style` for core blocks if missing.562	if ( ! empty( $metadata['name'] ) && str_starts_with( $metadata['name'], 'core/' ) ) {563		$block_name = str_replace( 'core/', '', $metadata['name'] );564 565		if ( ! isset( $metadata['style'] ) ) {566			$metadata['style'] = "wp-block-$block_name";567		}568		if ( current_theme_supports( 'wp-block-styles' ) && wp_should_load_separate_core_block_assets() ) {569			$metadata['style']   = (array) $metadata['style'];570			$metadata['style'][] = "wp-block-{$block_name}-theme";571		}572		if ( ! isset( $metadata['editorStyle'] ) ) {573			$metadata['editorStyle'] = "wp-block-{$block_name}-editor";574		}575	}576 577	$settings          = array();578	$property_mappings = array(579		'apiVersion'      => 'api_version',580		'name'            => 'name',581		'title'           => 'title',582		'category'        => 'category',583		'parent'          => 'parent',584		'ancestor'        => 'ancestor',585		'icon'            => 'icon',586		'description'     => 'description',587		'keywords'        => 'keywords',588		'attributes'      => 'attributes',589		'providesContext' => 'provides_context',590		'usesContext'     => 'uses_context',591		'selectors'       => 'selectors',592		'supports'        => 'supports',593		'styles'          => 'styles',594		'variations'      => 'variations',595		'example'         => 'example',596		'allowedBlocks'   => 'allowed_blocks',597	);598	$textdomain        = ! empty( $metadata['textdomain'] ) ? $metadata['textdomain'] : null;599	$i18n_schema       = get_block_metadata_i18n_schema();

Changelog

Introduced in 5.5.0. Unchanged from 6.7.7 through 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data

Generated from the wordpress-develop 7.1.0 tag, from src/wp-includes/blocks.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.

Corrections

Something wrong on this page? Report it and it gets fixed in the next regeneration.