From f08889ff98c0b419e67b7dd7362b7837c1976d0a Mon Sep 17 00:00:00 2001
From: Aaron Jorbin <aaron@jorb.in>
Date: Tue, 4 Feb 2025 02:49:18 +0000
Subject: [PATCH] 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.

Built from https://develop.svn.wordpress.org/branches/6.7@59757


git-svn-id: http://core.svn.wordpress.org/branches/6.7@59099 1a063a9b-81f0-0310-95a4-ce76da25c4cd
---
 .../html-api/class-wp-html-processor.php      | 33 +++++++++++++++----
 wp-includes/version.php                       |  2 +-
 2 files changed, 28 insertions(+), 7 deletions(-)

diff --git a/wp-includes/html-api/class-wp-html-processor.php b/wp-includes/html-api/class-wp-html-processor.php
index 7bb9a1bab4..ecb19ee988 100644
--- a/wp-includes/html-api/class-wp-html-processor.php
+++ b/wp-includes/html-api/class-wp-html-processor.php
@@ -607,6 +607,22 @@ public function next_tag( $query = null ): bool {
 		return false;
 	}
 
+	/**
+	 * Finds the next token in the HTML document.
+	 *
+	 * 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.
+	 *
+	 * @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.
@@ -615,13 +631,18 @@ public function next_tag( $query = null ): bool {
 	 * semantic rules for text nodes. For access to the raw tokens consider using
 	 * WP_HTML_Tag_Processor instead.
 	 *
-	 * @since 6.5.0 Added for internal support; do not use.
+	 * 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
 	 *
 	 * @return bool
 	 */
-	public function next_token(): bool {
+	private function next_visitable_token(): bool {
 		$this->current_element = null;
 
 		if ( isset( $this->last_error ) ) {
@@ -639,7 +660,7 @@ public function next_token(): bool {
 		 *       tokens works in the meantime and isn't obviously wrong.
 		 */
 		if ( empty( $this->element_queue ) && $this->step() ) {
-			return $this->next_token();
+			return $this->next_visitable_token();
 		}
 
 		// Process the next event on the queue.
@@ -650,7 +671,7 @@ public function next_token(): bool {
 				continue;
 			}
 
-			return empty( $this->element_queue ) ? false : $this->next_token();
+			return empty( $this->element_queue ) ? false : $this->next_visitable_token();
 		}
 
 		$is_pop = WP_HTML_Stack_Event::POP === $this->current_element->operation;
@@ -661,7 +682,7 @@ public function next_token(): bool {
 		 * the breadcrumbs.
 		 */
 		if ( 'root-node' === $this->current_element->token->bookmark_name ) {
-			return $this->next_token();
+			return $this->next_visitable_token();
 		}
 
 		// Adjust the breadcrumbs for this event.
@@ -673,7 +694,7 @@ public function next_token(): bool {
 
 		// 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();
 		}
 
 		return true;
diff --git a/wp-includes/version.php b/wp-includes/version.php
index b2ffbc54e9..f47ebdf9a9 100644
--- a/wp-includes/version.php
+++ b/wp-includes/version.php
@@ -16,7 +16,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '6.7.2-alpha-59745';
+$wp_version = '6.7.2-alpha-59757';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.