parse_blocks( string $content ): array[]
- Since
- 5.0.0
- Source
wp-includes/blocks.php:2474
Description
Given an HTML document, this function fully-parses block content, producing a tree of blocks and their contents, as well as top-level non-block content, which will appear as a block with no blockName.
This function can be memory heavy for certain documents, particularly those with deeply-nested blocks or blocks with extensive attribute values. Further, this function must parse an entire document in one atomic operation.
If the entire parsed document is not necessary, consider using WP_Block_Processor instead, as it provides a streaming and low-overhead interface for finding blocks.
Compatibility
- WordPress
- since 5.0.0
- PHP
- 7.4–8.6-dev
- 6.7.7
- 6.8.8
- 6.9.7
- 7.0.4
- 7.1.0
Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.
Parameters
$contentstring- Post content.
Return value
array[]- Array of block structures.
...$0arrayAn associative array of a single parsed block object. See WP_Block_Parser_Block.$blockNamestring|nullName of block.$attrsarrayAttributes from block comment delimiters.$innerBlocksarray[]List of inner blocks. An array of arrays that have the same structure as this one.$innerHTMLstringHTML from inside block comment delimiters.$innerContentarrayList of string fragments and null markers where inner blocks were found.
Performance profile
How much work a call to parse_blocks() 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
- Scaling
- Constant
- Instructions
- 14
- Plugin surface
- 1 hook
- Called by
- 21
Touches nothing outside its own arguments.
No loop in the body: the same number of instructions runs whatever you pass in.
Executed per call on PHP 8.5. The body compiles to 14.
Third-party callbacks on 'block_parser_class' run inside this call, and their cost is not bounded by anything here.
21 places in core call this, so the cost is paid more often than your own code shows.
What it touches
- hookthird-party callbacks
apply_filters()called directly
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 parse_blocks() can have, taken from its control-flow graph on PHP 8.5.
| When | Instructions | Calls it makes |
|---|---|---|
| always | 14 | apply_filters(), ->parse() |
Across PHP versions
Compiles the same on PHP 7.4, 8.1, 8.2, 8.3, 8.4, 8.5 and 8.6-dev: 14 instructions, 14 executed per call, 0 branches. The work does not change between versions.
An instruction is not a fixed amount of time, so a matching count is not necessarily the same speed; what it rules out is a difference in the work itself.
Hooks and filters fired · 1
One hook fires while parse_blocks() runs, in this order:
- apply_filters( block_parser_class )filterline 2482 (+8 into the body)
Filter to allow plugins to replace the server-side block parser.
Uses · 1
- apply_filters()Calls the callback functions that have been added to a filter hook.
Used by · 21
- WP_Navigation_Block_Renderer::get_inner_blocks_from_navigation_post()Gets the inner blocks for the navigation block from the navigation post.
- WP_Navigation_Block_Renderer::get_overlay_blocks_from_template_part()Gets the inner blocks for the navigation block from an overlay template part.
- WP_REST_Block_Patterns_Controller::prepare_item_for_response()Prepare a raw block pattern before it gets output in a REST API response.
- WP_REST_Templates_Controller::prepare_item_for_response()Prepare a single template output for response
- WP_Widget_Block::get_dynamic_classname()Calculates the classname to use in the block widget's container HTML.
- _inject_theme_attribute_in_block_template_content()Parses wp_template content and injects the active theme's stylesheet as a theme attribute into each wp_template_part
- _remove_theme_attribute_in_block_template_content()Parses a block template and removes the theme attribute from each template part.
- apply_block_hooks_to_content()Runs the hooked blocks algorithm on the given content.
- apply_block_hooks_to_content_from_post_object()Run the Block Hooks algorithm on a post object's content.
- block_core_navigation_get_fallback_blocks()Retrieves the appropriate fallback to be used on the front of the site when there is no menu assigned to the Nav block.
- do_blocks()Parses dynamic blocks out of `post_content` and re-renders them.
- excerpt_remove_blocks()Parses blocks out of a content string, and renders those appropriate for the excerpt.
Show all 21
- filter_block_content()Filters and sanitizes block content to remove non-allowable HTML from parsed block attribute values.
- get_post_galleries()Retrieves galleries from the passed post's content.
- inject_ignored_hooked_blocks_metadata_attributes()Inject ignoredHookedBlocks metadata attributes into a template or template part.
- render_block_core_block()Renders the `core/block` block on server.
- resolve_pattern_blocks()Replaces patterns in a block tree with their content.
- twenty_twenty_one_print_first_instance_of_block()Prints the first instance of a block in the content, and then break away.
- update_ignored_hooked_blocks_postmeta()Updates the wp_postmeta with the list of ignored hooked blocks where the inner blocks are stored as post content.
- wp_generate_block_templates_export_file()Creates an export of the current templates and template parts from the site editor at the specified path in a ZIP file.
- wp_get_post_content_block_attributes()Retrieves Post Content block attributes from the current post template.
Source code
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 );}Changelog
Introduced in 5.0.0. Unchanged from 6.7.7 through 7.1.0.
Signature, return type and hooks compared across 5 parsed releases.
About this page
- Parsed data
- Generated from the wordpress-develop 7.0.4 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.