Changeset 61294

Timestamp:

11/24/2025 09:52:17 PM (3 weeks ago)

Author:

dmsnell

Message:

Block Processor: Rename extract_block() method for clearer documentation.

In testing during the release candidacy for WordPress 6.9 it was found
that the extract_block() method may do more work than is expected
based off of its name.

This change renames the method to extract_full_block_and_advance() to
communicate that it does move the Block Processor forward and to hint at
the fact that it also encompasses all inner blocks during that advance.

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

Follow-up to [60939].

Props dlh, dmsnell, jonsurrell, westonruter.

See #61401.

Location:

trunk

Files:

• src/wp-includes/class-wp-block-processor.php (modified) (5 diffs)
• tests/phpunit/tests/block-processor/wpBlockProcessor-BlockProcessing.php (modified) (1 diff)

trunk/src/wp-includes/class-wp-block-processor.php

@@ -195 +195 @@
  * while skipping over the parse of the rest of the document.
  *
- * {@see self::extract_block()} will scan forward from the current block opener
+ * {@see self::extract_full_block_and_advance()} will scan forward from the current block opener
  * and build the parsed block structure until the current block is closed. It will
  * include all inner HTML and inner blocks, and parse all of the inner blocks. It
@@ -208 +208 @@
  *
  *     $gallery_at    = $processor->get_span()->start;
- *     $gallery_block = $processor->extract_block();
+ *     $gallery_block = $processor->extract_full_block_and_advance();
  *     $after_gallery = $processor->get_span()->start;
  *     return (
@@ -1224 +1224 @@
      *
      *     $gallery_at  = $processor->get_span()->start;
-     *     $gallery     = $processor->extract_block();
+     *     $gallery     = $processor->extract_full_block_and_advance();
      *     $ends_before = $processor->get_span();
      *     $ends_before = $ends_before->start ?? strlen( $post_content );
@@ -1255 +1255 @@
      * }
      */
-    public function extract_block(): ?array {
+    public function extract_full_block_and_advance(): ?array {
         if ( $this->is_html() ) {
             $chunk = $this->get_html_content();
@@ -1292 +1292 @@
              */
             if ( $this->opens_block() ) {
-                $inner_block             = $this->extract_block();
+                $inner_block             = $this->extract_full_block_and_advance();
                 $block['innerBlocks'][]  = $inner_block;
                 $block['innerContent'][] = null;

trunk/tests/phpunit/tests/block-processor/wpBlockProcessor-BlockProcessing.php

@@ -87 +87 @@
         $extracted = array();
         while ( $processor->next_block( '*' ) ) {
-            $extracted[] = $processor->extract_block();
+            $extracted[] = $processor->extract_full_block_and_advance();
         }