556 lines
17 KiB
PHP
556 lines
17 KiB
PHP
<?php
|
|
/**
|
|
* Functions related to registering and parsing blocks.
|
|
*
|
|
* @package WordPress
|
|
* @subpackage Blocks
|
|
* @since 5.0.0
|
|
*/
|
|
|
|
/**
|
|
* Registers a block type.
|
|
*
|
|
* @since 5.0.0
|
|
*
|
|
* @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. 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( $name, $args = array() ) {
|
|
return WP_Block_Type_Registry::get_instance()->register( $name, $args );
|
|
}
|
|
|
|
/**
|
|
* Unregisters a block type.
|
|
*
|
|
* @since 5.0.0
|
|
*
|
|
* @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 );
|
|
}
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* @since 5.0.0
|
|
* @see parse_blocks()
|
|
*
|
|
* @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.
|
|
*
|
|
* @since 5.0.0
|
|
* @see parse_blocks()
|
|
*
|
|
* @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 ) ) {
|
|
return false;
|
|
}
|
|
|
|
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 ( ! $has_block ) {
|
|
/*
|
|
* 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 . ' ' );
|
|
}
|
|
}
|
|
|
|
return $has_block;
|
|
}
|
|
|
|
/**
|
|
* Returns an array of the names of all registered dynamic block types.
|
|
*
|
|
* @since 5.0.0
|
|
*
|
|
* @return array 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.
|
|
*
|
|
* @since 5.3.1
|
|
*
|
|
* @param array $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 );
|
|
// Regex: /\\"/
|
|
$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.
|
|
*
|
|
* @since 5.3.1
|
|
*
|
|
* @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 );
|
|
}
|
|
|
|
return $block_name;
|
|
}
|
|
|
|
/**
|
|
* Returns the content of a block, including comment delimiters.
|
|
*
|
|
* @since 5.3.1
|
|
*
|
|
* @param string $block_name Block name.
|
|
* @param array $attributes Block attributes.
|
|
* @param string $content Block save content.
|
|
* @return string Comment-delimited block content.
|
|
*/
|
|
function get_comment_delimited_block_content( $block_name = null, $block_attributes, $block_content ) {
|
|
if ( is_null( $block_name ) ) {
|
|
return $block_content;
|
|
}
|
|
|
|
$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 );
|
|
}
|
|
|
|
return sprintf(
|
|
'<!-- wp:%s %s-->%s<!-- /wp:%s -->',
|
|
$serialized_block_name,
|
|
$serialized_attributes,
|
|
$block_content,
|
|
$serialized_block_name
|
|
);
|
|
}
|
|
|
|
/**
|
|
* Returns the content of a block, including comment delimiters, serializing all
|
|
* attributes from the given parsed block.
|
|
*
|
|
* This should be used when preparing a block to be saved to post content.
|
|
* Prefer `render_block` when preparing a block for display. Unlike
|
|
* `render_block`, this does not evaluate a block's `render_callback`, and will
|
|
* instead preserve the markup as parsed.
|
|
*
|
|
* @since 5.3.1
|
|
*
|
|
* @param WP_Block_Parser_Block $block A single parsed block object.
|
|
* @return string String of rendered HTML.
|
|
*/
|
|
function serialize_block( $block ) {
|
|
$block_content = '';
|
|
|
|
$index = 0;
|
|
foreach ( $block['innerContent'] as $chunk ) {
|
|
$block_content .= is_string( $chunk ) ? $chunk : serialize_block( $block['innerBlocks'][ $index++ ] );
|
|
}
|
|
|
|
if ( ! is_array( $block['attrs'] ) ) {
|
|
$block['attrs'] = array();
|
|
}
|
|
|
|
return get_comment_delimited_block_content(
|
|
$block['blockName'],
|
|
$block['attrs'],
|
|
$block_content
|
|
);
|
|
}
|
|
|
|
/**
|
|
* Returns a joined string of the aggregate serialization of the given parsed
|
|
* blocks.
|
|
*
|
|
* @since 5.3.1
|
|
*
|
|
* @param WP_Block_Parser_Block[] $blocks Parsed block objects.
|
|
* @return string String of rendered HTML.
|
|
*/
|
|
function serialize_blocks( $blocks ) {
|
|
return implode( '', array_map( 'serialize_block', $blocks ) );
|
|
}
|
|
|
|
/**
|
|
* Filters and sanitizes block content to remove non-allowable HTML from
|
|
* parsed block attribute values.
|
|
*
|
|
* @since 5.3.1
|
|
*
|
|
* @param string $text Text that may contain block content.
|
|
* @param array[]|string $allowed_html An array of allowed HTML elements
|
|
* and attributes, or a context name
|
|
* such as 'post'.
|
|
* @param string[] $allowed_protocols Array of allowed URL protocols.
|
|
* @return string The filtered and sanitized content result.
|
|
*/
|
|
function filter_block_content( $text, $allowed_html = 'post', $allowed_protocols = array() ) {
|
|
$result = '';
|
|
|
|
if ( false !== strpos( $text, '<!--' ) && false !== strpos( $text, '--->' ) ) {
|
|
$text = preg_replace_callback( '%<!--(.*?)--->%', '_filter_block_content_callback', $text );
|
|
}
|
|
|
|
$blocks = parse_blocks( $text );
|
|
foreach ( $blocks as $block ) {
|
|
$block = filter_block_kses( $block, $allowed_html, $allowed_protocols );
|
|
$result .= serialize_block( $block );
|
|
}
|
|
|
|
return $result;
|
|
}
|
|
|
|
/**
|
|
* Callback used for regular expression replacement in filter_block_content().
|
|
*
|
|
* @private
|
|
* @since 6.2.1
|
|
*
|
|
* @param array $matches Array of preg_replace_callback matches.
|
|
* @return string Replacement string.
|
|
*/
|
|
function _filter_block_content_callback( $matches ) {
|
|
return '<!--' . rtrim( $matches[1], '-' ) . '-->';
|
|
}
|
|
|
|
/**
|
|
* Filters and sanitizes a parsed block to remove non-allowable HTML from block
|
|
* attribute values.
|
|
*
|
|
* @since 5.3.1
|
|
*
|
|
* @param WP_Block_Parser_Block $block The parsed block object.
|
|
* @param array[]|string $allowed_html An array of allowed HTML
|
|
* elements and attributes, or a
|
|
* context name such as 'post'.
|
|
* @param string[] $allowed_protocols Allowed URL protocols.
|
|
* @return array The filtered and sanitized block object result.
|
|
*/
|
|
function filter_block_kses( $block, $allowed_html, $allowed_protocols = array() ) {
|
|
$block['attrs'] = filter_block_kses_value( $block['attrs'], $allowed_html, $allowed_protocols );
|
|
|
|
if ( is_array( $block['innerBlocks'] ) ) {
|
|
foreach ( $block['innerBlocks'] as $i => $inner_block ) {
|
|
$block['innerBlocks'][ $i ] = filter_block_kses( $inner_block, $allowed_html, $allowed_protocols );
|
|
}
|
|
}
|
|
|
|
return $block;
|
|
}
|
|
|
|
/**
|
|
* Filters and sanitizes a parsed block attribute value to remove non-allowable
|
|
* HTML.
|
|
*
|
|
* @since 5.3.1
|
|
*
|
|
* @param mixed $value The attribute value to filter.
|
|
* @param array[]|string $allowed_html An array of allowed HTML elements
|
|
* and attributes, or a context name
|
|
* such as 'post'.
|
|
* @param string[] $allowed_protocols Array of allowed URL protocols.
|
|
* @return array The filtered and sanitized result.
|
|
*/
|
|
function filter_block_kses_value( $value, $allowed_html, $allowed_protocols = array() ) {
|
|
if ( is_array( $value ) ) {
|
|
foreach ( $value as $key => $inner_value ) {
|
|
$filtered_key = filter_block_kses_value( $key, $allowed_html, $allowed_protocols );
|
|
$filtered_value = filter_block_kses_value( $inner_value, $allowed_html, $allowed_protocols );
|
|
|
|
if ( $filtered_key !== $key ) {
|
|
unset( $value[ $key ] );
|
|
}
|
|
|
|
$value[ $filtered_key ] = $filtered_value;
|
|
}
|
|
} elseif ( is_string( $value ) ) {
|
|
return wp_kses( $value, $allowed_html, $allowed_protocols );
|
|
}
|
|
|
|
return $value;
|
|
}
|
|
|
|
/**
|
|
* Parses blocks out of a content string, and renders those appropriate for the excerpt.
|
|
*
|
|
* As the excerpt should be a small string of text relevant to the full post content,
|
|
* this function renders the blocks that are most likely to contain such text.
|
|
*
|
|
* @since 5.0.0
|
|
*
|
|
* @param string $content The content to parse.
|
|
* @return string The parsed and filtered content.
|
|
*/
|
|
function excerpt_remove_blocks( $content ) {
|
|
$allowed_blocks = array(
|
|
// Classic blocks have their blockName set to null.
|
|
null,
|
|
'core/columns',
|
|
'core/freeform',
|
|
'core/heading',
|
|
'core/html',
|
|
'core/list',
|
|
'core/media-text',
|
|
'core/paragraph',
|
|
'core/preformatted',
|
|
'core/pullquote',
|
|
'core/quote',
|
|
'core/table',
|
|
'core/verse',
|
|
);
|
|
/**
|
|
* Filters the list of blocks that can contribute to the excerpt.
|
|
*
|
|
* If a dynamic block is added to this list, it must not generate another
|
|
* excerpt, as this will cause an infinite loop to occur.
|
|
*
|
|
* @since 4.4.0
|
|
*
|
|
* @param array $allowed_blocks The list of allowed blocks.
|
|
*/
|
|
$allowed_blocks = apply_filters( 'excerpt_allowed_blocks', $allowed_blocks );
|
|
$blocks = parse_blocks( $content );
|
|
$output = '';
|
|
foreach ( $blocks as $block ) {
|
|
if ( in_array( $block['blockName'], $allowed_blocks, true ) ) {
|
|
$output .= render_block( $block );
|
|
}
|
|
}
|
|
return $output;
|
|
}
|
|
|
|
/**
|
|
* Renders a single block into a HTML string.
|
|
*
|
|
* @since 5.0.0
|
|
*
|
|
* @global WP_Post $post The post to edit.
|
|
*
|
|
* @param array $block A single parsed block object.
|
|
* @return string String of rendered HTML.
|
|
*/
|
|
function render_block( $block ) {
|
|
global $post;
|
|
|
|
/**
|
|
* Allows render_block() to be shortcircuited, by returning a non-null value.
|
|
*
|
|
* @since 5.1.0
|
|
*
|
|
* @param string $pre_render The pre-rendered content. Default null.
|
|
* @param array $block The block being rendered.
|
|
*/
|
|
$pre_render = apply_filters( 'pre_render_block', null, $block );
|
|
if ( ! is_null( $pre_render ) ) {
|
|
return $pre_render;
|
|
}
|
|
|
|
$source_block = $block;
|
|
|
|
/**
|
|
* Filters the block being rendered in render_block(), before it's processed.
|
|
*
|
|
* @since 5.1.0
|
|
*
|
|
* @param array $block The block being rendered.
|
|
* @param array $source_block An un-modified copy of $block, as it appeared in the source content.
|
|
*/
|
|
$block = apply_filters( 'render_block_data', $block, $source_block );
|
|
|
|
$block_type = WP_Block_Type_Registry::get_instance()->get_registered( $block['blockName'] );
|
|
$is_dynamic = $block['blockName'] && null !== $block_type && $block_type->is_dynamic();
|
|
$block_content = '';
|
|
$index = 0;
|
|
|
|
foreach ( $block['innerContent'] as $chunk ) {
|
|
$block_content .= is_string( $chunk ) ? $chunk : render_block( $block['innerBlocks'][ $index++ ] );
|
|
}
|
|
|
|
if ( ! is_array( $block['attrs'] ) ) {
|
|
$block['attrs'] = array();
|
|
}
|
|
|
|
if ( $is_dynamic ) {
|
|
$global_post = $post;
|
|
$block_content = $block_type->render( $block['attrs'], $block_content );
|
|
$post = $global_post;
|
|
}
|
|
|
|
/**
|
|
* Filters the content of a single block.
|
|
*
|
|
* @since 5.0.0
|
|
*
|
|
* @param string $block_content The block content about to be appended.
|
|
* @param array $block The full block, including name and attributes.
|
|
*/
|
|
return apply_filters( 'render_block', $block_content, $block );
|
|
}
|
|
|
|
/**
|
|
* Parses blocks out of a content string.
|
|
*
|
|
* @since 5.0.0
|
|
*
|
|
* @param string $content Post content.
|
|
* @return array Array of parsed block objects.
|
|
*/
|
|
function parse_blocks( $content ) {
|
|
/**
|
|
* Filter to allow plugins to replace the server-side block parser
|
|
*
|
|
* @since 5.0.0
|
|
*
|
|
* @param string $parser_class Name of block parser class.
|
|
*/
|
|
$parser_class = apply_filters( 'block_parser_class', 'WP_Block_Parser' );
|
|
|
|
$parser = new $parser_class();
|
|
return $parser->parse( $content );
|
|
}
|
|
|
|
/**
|
|
* Parses dynamic blocks out of `post_content` and re-renders them.
|
|
*
|
|
* @since 5.0.0
|
|
* @global WP_Post $post The post to edit.
|
|
*
|
|
* @param string $content Post content.
|
|
* @return string Updated post content.
|
|
*/
|
|
function do_blocks( $content ) {
|
|
// If there are blocks in this content, we shouldn't run wpautop() on it later.
|
|
$priority = has_filter( 'the_content', 'wpautop' );
|
|
if ( false !== $priority && doing_filter( 'the_content' ) && has_blocks( $content ) ) {
|
|
remove_filter( 'the_content', 'wpautop', $priority );
|
|
add_filter( 'the_content', '_restore_wpautop_hook', $priority + 1 );
|
|
}
|
|
|
|
$blocks = parse_blocks( $content );
|
|
$output = '';
|
|
|
|
foreach ( $blocks as $block ) {
|
|
$output .= render_block( $block );
|
|
}
|
|
|
|
return $output;
|
|
}
|
|
|
|
/**
|
|
* If do_blocks() needs to remove wp_autop() from the `the_content` filter, this re-adds it afterwards,
|
|
* for subsequent `the_content` usage.
|
|
*
|
|
* @access private
|
|
*
|
|
* @since 5.0.0
|
|
*
|
|
* @param string $content The post content running through this filter.
|
|
* @return string The unmodified content.
|
|
*/
|
|
function _restore_wpautop_hook( $content ) {
|
|
$current_priority = has_filter( 'the_content', '_restore_wpautop_hook' );
|
|
|
|
add_filter( 'the_content', 'wpautop', $current_priority - 1 );
|
|
remove_filter( 'the_content', '_restore_wpautop_hook', $current_priority );
|
|
|
|
return $content;
|
|
}
|
|
|
|
/**
|
|
* Returns the current version of the block format that the content string is using.
|
|
*
|
|
* If the string doesn't contain blocks, it returns 0.
|
|
*
|
|
* @since 5.0.0
|
|
*
|
|
* @param string $content Content to test.
|
|
* @return int The block format version is 1 if the content contains one or more blocks, 0 otherwise.
|
|
*/
|
|
function block_version( $content ) {
|
|
return has_blocks( $content ) ? 1 : 0;
|
|
}
|