Extracts a block object, and all inner content, starting at a matched opening block delimiter, or at a matched top-level HTML span as freeform HTML content.
Description
Use this function to extract some blocks within a document, but not all. For example, one might want to find image galleries, parse them, modify them, and then reserialize them in place. Once this function returns, the parser will be matched on token following the close of the given block. The return type of this method is compatible with the return of parse_blocks(). Example: $processor = new WP_Block_Processor( $post_content );
if ( ! $processor->next_block( 'gallery' ) ) {
return $post_content;
}
$gallery_at = $processor->get_span()->start;
$gallery = $processor->extract_full_block_and_advance();
$ends_before = $processor->get_span();
$ends_before = $ends_before->start ?? strlen( $post_content );
$new_gallery = update_gallery( $gallery );
$new_gallery = serialize_block( $new_gallery );
return (
substr( $post_content, 0, $gallery_at ) .
$new_gallery .
substr( $post_content, $ends_before )
);
Return
array[]|null
Array of block structures.
...$0array
An associative array of a single parsed block object. See WP_Block_Parser_Block.
$blockNamestring|null
Name of block.
$attrsarray
Attributes from block comment delimiters.
$innerBlocksarray[]
List of inner blocks. An array of arrays that have the same structure as this one.
$innerHTMLstring
HTML from inside block comment delimiters.
$innerContentarray
List of string fragments and null markers where inner blocks were found.
WP_Block_Processor::get_block_type()Allocates a substring for the block type and returns the fully-qualified name, including the namespace, if matched on a delimiter, otherwise `null`.
WP_Block_Processor::opens_block()Indicates if the matched delimiter is an opening or void delimiter of the given type, if a type is provided, otherwise if it opens any block or implicit freeform HTML content.
WP_Block_Processor::extract_full_block_and_advance()Extracts a block object, and all inner content, starting at a matched opening block delimiter, or at a matched top-level HTML span as freeform HTML content.
Used by · 1
WP_Block_Processor::extract_full_block_and_advance()Extracts a block object, and all inner content, starting at a matched opening block delimiter, or at a matched top-level HTML span as freeform HTML content.
1257publicfunctionextract_full_block_and_advance():?array{1258if($this->is_html()){1259$chunk=$this->get_html_content();12601261returnarray(1262'blockName'=>null,1263'attrs'=>array(),1264'innerBlocks'=>array(),1265'innerHTML'=>$chunk,1266'innerContent'=>array($chunk),1267);1268}12691270$block=array(1271'blockName'=>$this->get_block_type(),1272'attrs'=>$this->allocate_and_return_parsed_attributes()??array(),1273'innerBlocks'=>array(),1274'innerHTML'=>'',1275'innerContent'=>array(),1276);12771278$depth=$this->get_depth();1279while($this->next_token()&&$this->get_depth()>$depth){1280if($this->is_html()){1281$chunk=$this->get_html_content();1282$block['innerHTML'].=$chunk;1283$block['innerContent'][]=$chunk;1284continue;1285}12861287/**1288 * Inner blocks.1289 *1290 * @todo This is a decent place to call {@link \render_block()}1291 * @todo Use iteration instead of recursion, or at least refactor to tail-call form.1292 */1293if($this->opens_block()){1294$inner_block=$this->extract_full_block_and_advance();1295$block['innerBlocks'][]=$inner_block;1296$block['innerContent'][]=null;1297}12981299/*1300 * Because the parser has advanced past the closing block token, it1301 * may be matched on an HTML span. This needs to be processed before1302 * moving on to the next token at the start of the next loop iteration.1303 */1304if($this->is_html()){1305$chunk=$this->get_html_content();1306$block['innerHTML'].=$chunk;1307$block['innerContent'][]=$chunk;1308}1309}13101311return$block;1312}
History
Introduced in 6.9.0. Unchanged from 6.9.7 through 7.1.0.
Signature, return type and hooks compared across 3 parsed releases.
About this page
Parsed data
Generated from the wordpress-develop 7.0.4 tag, from src/wp-includes/class-wp-block-processor.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.