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

Timestamp:

02/04/2025 02:47:41 AM (19 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();
                 }