Blocks: Introduce WP_Block_Scanner for efficiently parsing blocks.

The Block Scanner follows the HTML API in providing a streaming,
near-zero-overhead, lazy, re-entrant parser for traversing block
structure. This class provides an alternate interface to
`parse_blocks()` which is more amenable to a number of common
server-side operations on posts, such as:

 - Generating an excerpt from only the first N blocks in a post.
 - Determining which block types are present in a post.
 - Determining which posts contain a block of a given type.
 - Generating block supports content for a post.

Author: dmsnell

phpcs.xml.dist

@@ -229,7 +229,7 @@
 	#############################################################################
 	SELECTIVE EXCLUSIONS
 	Exclude specific files for specific sniffs and/or exclude sub-groups in sniffs.
-	
+
 	These exclusions are listed ordered by alphabetic sniff name.
 	#############################################################################
 	-->
@@ -266,8 +266,9 @@
 
 		<!-- Goto is an effective way to handle errors in decoders which expect valid bytes
 		     without impacting the fast path while avoiding bloating the code with redundant
-		     and risky handling code. Exclude forbidding goto in UTF-8 fallback code. -->
+		     and risky handling code. Exclude forbidding goto in parser code. -->
 		<exclude-pattern>/wp-includes/compat-utf8\.php</exclude-pattern>
+		<exclude-pattern>/wp-includes/class-wp-block-processor\.php</exclude-pattern>
 	</rule>
 
 	<!-- Exclude sample config from modernization to prevent breaking CI workflows based on WP-CLI scaffold.

src/wp-includes/blocks.php

@@ -2376,6 +2376,17 @@ function render_block( $parsed_block ) {
 /**
  * Parses blocks out of a content string.
  *
+ * 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 {@see WP_Block_Processor}
+ * instead, as it provides a streaming and low-overhead interface for finding blocks.
+ *
  * @since 5.0.0
  *
  * @param string $content Post content.