* Functions related to registering and parsing blocks.
* Registers a block type.
* @param string|WP_Block_Type $name Block type name including namespace, or alternatively
* a complete WP_Block_Type instance. In case a WP_Block_Type
* is provided, the $args parameter will be ignored.
* @param array $args Optional. 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.
* @return WP_Block_Type|false The registered block type on success, or false on failure.
function register_block_type( $name, $args = array() ) {
return WP_Block_Type_Registry::get_instance()->register( $name, $args );
* Unregisters a block type.
* @param string|WP_Block_Type $name Block type name including namespace, or alternatively
* a complete WP_Block_Type instance.
* @return WP_Block_Type|false The unregistered block type on success, or false on failure.
function unregister_block_type( $name ) {
return WP_Block_Type_Registry::get_instance()->unregister( $name );
* Removes the block asset's path prefix if provided.
* @param string $asset_handle_or_path Asset handle or prefixed path.
* @return string Path without the prefix or the original value.
function remove_block_asset_path_prefix( $asset_handle_or_path ) {
if ( 0 !== strpos( $asset_handle_or_path, $path_prefix ) ) {
return $asset_handle_or_path;
* Generates the name for an asset based on the name of the block
* and the field name provided.
* @param string $block_name Name of the block.
* @param string $field_name Name of the metadata field.
* @return string Generated asset name for the block's field.
function generate_block_asset_handle( $block_name, $field_name ) {
if ( 0 === strpos( $block_name, 'core/' ) ) {
$asset_handle = str_replace( 'core/', 'wp-block-', $block_name );
if ( 0 === strpos( $field_name, 'editor' ) ) {
$asset_handle .= '-editor';
'editorScript' => 'editor-script',
'editorStyle' => 'editor-style',
return str_replace( '/', '-', $block_name ) .
'-' . $field_mappings[ $field_name ];
* Finds a script handle for the selected block metadata field. It detects
* when a path to file was provided and finds a corresponding asset file
* with details necessary to register the script under automatically
* generated handle name. It returns unprocessed script handle otherwise.
* @param array $metadata Block metadata.
* @param string $field_name Field name to pick from metadata.
* @return string|false Script handle provided directly or created through
* script's registration, or false on failure.
function register_block_script_handle( $metadata, $field_name ) {
if ( empty( $metadata[ $field_name ] ) ) {
$script_handle = $metadata[ $field_name ];
$script_path = remove_block_asset_path_prefix( $metadata[ $field_name ] );
if ( $script_handle === $script_path ) {
$script_handle = generate_block_asset_handle( $metadata['name'], $field_name );
$script_asset_path = realpath(
dirname( $metadata['file'] ) . '/' .
substr_replace( $script_path, '.asset.php', - strlen( '.js' ) )
if ( ! file_exists( $script_asset_path ) ) {
/* translators: %1: field name. %2: block name */
__( 'The asset file for the "%1$s" defined in "%2$s" block definition is missing.', 'default' ),
_doing_it_wrong( __FUNCTION__, $message, '5.5.0' );
$script_asset = require $script_asset_path;
$result = wp_register_script(
plugins_url( $script_path, $metadata['file'] ),
$script_asset['dependencies'],
if ( ! empty( $metadata['textdomain'] ) ) {
wp_set_script_translations( $script_handle, $metadata['textdomain'] );
* Finds a style handle for the block metadata field. It detects when a path
* to file was provided and registers the style under automatically
* generated handle name. It returns unprocessed style handle otherwise.
* @param array $metadata Block metadata.
* @param string $field_name Field name to pick from metadata.
* @return string|false Style handle provided directly or created through
* style's registration, or false on failure.
function register_block_style_handle( $metadata, $field_name ) {
if ( empty( $metadata[ $field_name ] ) ) {
$style_handle = $metadata[ $field_name ];
$style_path = remove_block_asset_path_prefix( $metadata[ $field_name ] );
if ( $style_handle === $style_path ) {
$style_handle = generate_block_asset_handle( $metadata['name'], $field_name );
$block_dir = dirname( $metadata['file'] );
$style_file = realpath( "$block_dir/$style_path" );
$result = wp_register_style(
plugins_url( $style_path, $metadata['file'] ),
if ( file_exists( str_replace( '.css', '-rtl.css', $style_file ) ) ) {
wp_style_add_data( $style_handle, 'rtl', 'replace' );
return $result ? $style_handle : false;
* Registers a block type from metadata stored in the `block.json` file.
* @param string $file_or_folder Path to the JSON file with metadata definition for
* the block or path to the folder where the `block.json` file is located.
* @param array $args Optional. 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.
* @return WP_Block_Type|false The registered block type on success, or false on failure.
function register_block_type_from_metadata( $file_or_folder, $args = array() ) {
$filename = 'block.json';
$metadata_file = ( substr( $file_or_folder, -strlen( $filename ) ) !== $filename ) ?
trailingslashit( $file_or_folder ) . $filename :
if ( ! file_exists( $metadata_file ) ) {
$metadata = json_decode( file_get_contents( $metadata_file ), true );
if ( ! is_array( $metadata ) || empty( $metadata['name'] ) ) {
$metadata['file'] = $metadata_file;
* Filters the metadata provided for registering a block type.
* @param array $metadata Metadata for registering a block type.
$metadata = apply_filters( 'block_type_metadata', $metadata );
$property_mappings = array(
'category' => 'category',
'description' => 'description',
'keywords' => 'keywords',
'attributes' => 'attributes',
'providesContext' => 'provides_context',
'usesContext' => 'uses_context',
'supports' => 'supports',
'apiVersion' => 'api_version',
foreach ( $property_mappings as $key => $mapped_key ) {
if ( isset( $metadata[ $key ] ) ) {
$value = $metadata[ $key ];
if ( empty( $metadata['textdomain'] ) ) {
$settings[ $mapped_key ] = $value;
$textdomain = $metadata['textdomain'];
// phpcs:ignore WordPress.WP.I18n.LowLevelTranslationFunction,WordPress.WP.I18n.NonSingularStringLiteralText,WordPress.WP.I18n.NonSingularStringLiteralContext,WordPress.WP.I18n.NonSingularStringLiteralDomain
$settings[ $mapped_key ] = translate_with_gettext_context( $value, sprintf( 'block %s', $key ), $textdomain );
$settings[ $mapped_key ] = array();
if ( ! is_array( $value ) ) {
foreach ( $value as $keyword ) {
// phpcs:ignore WordPress.WP.I18n.LowLevelTranslationFunction,WordPress.WP.I18n.NonSingularStringLiteralText,WordPress.WP.I18n.NonSingularStringLiteralDomain
$settings[ $mapped_key ][] = translate_with_gettext_context( $keyword, 'block keyword', $textdomain );
$settings[ $mapped_key ] = array();
if ( ! is_array( $value ) ) {
foreach ( $value as $style ) {
if ( ! empty( $style['label'] ) ) {
// phpcs:ignore WordPress.WP.I18n.LowLevelTranslationFunction,WordPress.WP.I18n.NonSingularStringLiteralText,WordPress.WP.I18n.NonSingularStringLiteralDomain
$style['label'] = translate_with_gettext_context( $style['label'], 'block style label', $textdomain );
$settings[ $mapped_key ][] = $style;
$settings[ $mapped_key ] = $value;
if ( ! empty( $metadata['editorScript'] ) ) {
$settings['editor_script'] = register_block_script_handle(
if ( ! empty( $metadata['script'] ) ) {
$settings['script'] = register_block_script_handle(
if ( ! empty( $metadata['editorStyle'] ) ) {
$settings['editor_style'] = register_block_style_handle(
if ( ! empty( $metadata['style'] ) ) {
$settings['style'] = register_block_style_handle(
* Filters the settings determined from the block type metadata.
* @param array $settings Array of determined settings for registering a block type.
* @param array $metadata Metadata provided for registering a block type.
$settings = apply_filters(
'block_type_metadata_settings',
return register_block_type(
* Determine whether a post or content string has blocks.
* This test optimizes for performance rather than strict accuracy, detecting
* the pattern of a block but not validating its structure. For strict accuracy,
* you should use the block parser on post content.
* @param int|string|WP_Post|null $post Optional. Post content, post ID, or post object. Defaults to global $post.
* @return bool Whether the post has blocks.
function has_blocks( $post = null ) {
if ( ! is_string( $post ) ) {
$wp_post = get_post( $post );
if ( $wp_post instanceof WP_Post ) {
$post = $wp_post->post_content;
return false !== strpos( (string) $post, '<!-- wp:' );
* Determine whether a $post or a string contains a specific block type.
* This test optimizes for performance rather than strict accuracy, detecting
* the block type exists but not validating its structure. For strict accuracy,
* you should use the block parser on post content.
* @param string $block_name Full Block type to look for.
* @param int|string|WP_Post|null $post Optional. Post content, post ID, or post object. Defaults to global $post.
* @return bool Whether the post content contains the specified block.
function has_block( $block_name, $post = null ) {
if ( ! has_blocks( $post ) ) {
if ( ! is_string( $post ) ) {
$wp_post = get_post( $post );
if ( $wp_post instanceof WP_Post ) {
$post = $wp_post->post_content;
* Normalize block name to include namespace, if provided as non-namespaced.
* This matches behavior for WordPress 5.0.0 - 5.3.0 in matching blocks by
* their serialized names.
if ( false === strpos( $block_name, '/' ) ) {
$block_name = 'core/' . $block_name;
// Test for existence of block by its fully qualified name.
$has_block = false !== strpos( $post, '<!-- wp:' . $block_name . ' ' );
* If the given block name would serialize to a different name, test for
* existence by the serialized form.
$serialized_block_name = strip_core_block_namespace( $block_name );
if ( $serialized_block_name !== $block_name ) {
$has_block = false !== strpos( $post, '<!-- wp:' . $serialized_block_name . ' ' );
* Returns an array of the names of all registered dynamic block types.
* @return string[] Array of dynamic block names.
function get_dynamic_block_names() {
$dynamic_block_names = array();
$block_types = WP_Block_Type_Registry::get_instance()->get_all_registered();
foreach ( $block_types as $block_type ) {
if ( $block_type->is_dynamic() ) {
$dynamic_block_names[] = $block_type->name;
return $dynamic_block_names;
* Given an array of attributes, returns a string in the serialized attributes
* format prepared for post content.
* The serialized result is a JSON-encoded string, with unicode escape sequence
* substitution for characters which might otherwise interfere with embedding
* the result in an HTML comment.
* @param array $block_attributes Attributes object.
* @return string Serialized attributes.
function serialize_block_attributes( $block_attributes ) {
$encoded_attributes = json_encode( $block_attributes );
$encoded_attributes = preg_replace( '/--/', '\\u002d\\u002d', $encoded_attributes );
$encoded_attributes = preg_replace( '/</', '\\u003c', $encoded_attributes );
$encoded_attributes = preg_replace( '/>/', '\\u003e', $encoded_attributes );
$encoded_attributes = preg_replace( '/&/', '\\u0026', $encoded_attributes );
$encoded_attributes = preg_replace( '/\\\\"/', '\\u0022', $encoded_attributes );
return $encoded_attributes;
* Returns the block name to use for serialization. This will remove the default
* "core/" namespace from a block name.
* @param string $block_name Original block name.
* @return string Block name to use for serialization.
function strip_core_block_namespace( $block_name = null ) {
if ( is_string( $block_name ) && 0 === strpos( $block_name, 'core/' ) ) {
return substr( $block_name, 5 );
* Returns the content of a block, including comment delimiters.
* @param string|null $block_name Block name. Null if the block name is unknown,
* e.g. Classic blocks have their name set to null.
* @param array $block_attributes Block attributes.
* @param string $block_content Block save content.
* @return string Comment-delimited block content.
function get_comment_delimited_block_content( $block_name, $block_attributes, $block_content ) {
if ( is_null( $block_name ) ) {
$serialized_block_name = strip_core_block_namespace( $block_name );
$serialized_attributes = empty( $block_attributes ) ? '' : serialize_block_attributes( $block_attributes ) . ' ';
if ( empty( $block_content ) ) {
return sprintf( '<!-- wp:%s %s/-->', $serialized_block_name, $serialized_attributes );
'<!-- wp:%s %s-->%s<!-- /wp:%s -->',
It is recommended that you Edit text format, this type of Fix handles quite a lot in one request
