Changeset 59757 for branches/6.7/src/wp-includes/html-api/class-wp-html-processor.php

Timestamp:

02/04/2025 02:47:41 AM (5 months ago)

Author:

jorbin

Message:

HTML API: Fix extensibility of WP_HTML_Processor::next_token().

Break out logic from the next_token() method into a private method which may call itself recursively. This allows for subclasses to override the next_token() method and be assured that each call to next_token() corresponds with the consumption of one single token. This also parallels how WP_HTML_Tag_Processor::next_token() wraps a private base_class_next_token() method.

Reviewed by jonsurrell.
Merges [59285], [59364], and [59747] to 6.7 branch.

Props westonruter, jonsurrell, dmsnell, jorbin.

File:

• branches/6.7/src/wp-includes/html-api/class-wp-html-processor.php (modified) (7 diffs)

branches/6.7/src/wp-includes/html-api/class-wp-html-processor.php

@@ -609 +609 @@
 
     /**
-     * Ensures internal accounting is maintained for HTML semantic rules while
-     * the underlying Tag Processor class is seeking to a bookmark.
+     * Finds the next token in the HTML document.
      *
      * This doesn't currently have a way to represent non-tags and doesn't process
@@ -617 +616 @@
      *
      * @since 6.5.0 Added for internal support; do not use.
+     * @since 6.7.2 Refactored so subclasses may extend.
+     *
+     * @return bool Whether a token was parsed.
+     */
+    public function next_token(): bool {
+        return $this->next_visitable_token();
+    }
+
+    /**
+     * Ensures internal accounting is maintained for HTML semantic rules while
+     * the underlying Tag Processor class is seeking to a bookmark.
+     *
+     * This doesn't currently have a way to represent non-tags and doesn't process
+     * semantic rules for text nodes. For access to the raw tokens consider using
+     * WP_HTML_Tag_Processor instead.
+     *
+     * Note that this method may call itself recursively. This is why it is not
+     * implemented as {@see WP_HTML_Processor::next_token()}, which instead calls
+     * this method similarly to how {@see WP_HTML_Tag_Processor::next_token()}
+     * calls the {@see WP_HTML_Tag_Processor::base_class_next_token()} method.
+     *
+     * @since 6.7.2 Added for internal support.
      *
      * @access private
@@ -622 +643 @@
      * @return bool
      */
-    public function next_token(): bool {
+    private function next_visitable_token(): bool {
         $this->current_element = null;
 
@@ -640 +661 @@
          */
         if ( empty( $this->element_queue ) && $this->step() ) {
-            return $this->next_token();
+            return $this->next_visitable_token();
         }
 
@@ -651 +672 @@
             }
 
-            return empty( $this->element_queue ) ? false : $this->next_token();
+            return empty( $this->element_queue ) ? false : $this->next_visitable_token();
         }
 
@@ -662 +683 @@
          */
         if ( 'root-node' === $this->current_element->token->bookmark_name ) {
-            return $this->next_token();
+            return $this->next_visitable_token();
         }
 
@@ -674 +695 @@
         // Avoid sending close events for elements which don't expect a closing.
         if ( $is_pop && ! $this->expects_closer( $this->current_element->token ) ) {
-            return $this->next_token();
+            return $this->next_visitable_token();
         }