Changeset 60939

Timestamp:

10/15/2025 09:51:35 PM (2 months ago)

Author:

dmsnell

Message:

Blocks: Introduce WP_Block_Processor for efficiently parsing blocks.

The Block Processor 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, especially those needing to operate on only a part of a full post.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/9105
Discussed in https://core.trac.wordpress.org/ticket/61401

Props dmsnell, gziolo, jonsurrell, soean, tjnowell, westonruter.
Fixes #61401.

Location:

trunk

Files:

• phpcs.xml.dist (modified) (2 diffs)
• src/wp-includes/blocks.php (modified) (1 diff)
• src/wp-includes/class-wp-block-processor.php (added)
• src/wp-settings.php (modified) (1 diff)
• tests/phpunit/tests/block-processor (added)
• tests/phpunit/tests/block-processor/wpBlockProcessor-BlockProcessing.php (added)
• tests/phpunit/tests/block-processor/wpBlockProcessor.php (added)

trunk/phpcs.xml.dist

@@ -230 +230 @@
     SELECTIVE EXCLUSIONS
     Exclude specific files for specific sniffs and/or exclude sub-groups in sniffs.
-    
+
     These exclusions are listed ordered by alphabetic sniff name.
     #############################################################################
@@ -267 +267 @@
         <!-- 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>
 

trunk/src/wp-includes/blocks.php

@@ -2377 +2377 @@
  * 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
  *

trunk/src/wp-settings.php

@@ -269 +269 @@
 require ABSPATH . WPINC . '/html-api/class-wp-html-processor-state.php';
 require ABSPATH . WPINC . '/html-api/class-wp-html-processor.php';
+require ABSPATH . WPINC . '/class-wp-block-processor.php';
 require ABSPATH . WPINC . '/class-wp-http.php';
 require ABSPATH . WPINC . '/class-wp-http-streams.php';