From 204d60314b202bbd912fe3c9941494f8e0809d18 Mon Sep 17 00:00:00 2001
From: Weston Ruter <weston@xwp.co>
Date: Wed, 23 Oct 2024 22:05:17 +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.

Props westonruter, jonsurrell.
Fixes #62269.

Built from https://develop.svn.wordpress.org/trunk@59285


git-svn-id: http://core.svn.wordpress.org/trunk@58677 1a063a9b-81f0-0310-95a4-ce76da25c4cd
---
 .../html-api/class-wp-html-processor.php      | 28 +++++++++++++++----
 wp-includes/version.php                       |  2 +-
 2 files changed, 23 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 b91c244887..4003cf48c1 100644
--- a/wp-includes/html-api/class-wp-html-processor.php
+++ b/wp-includes/html-api/class-wp-html-processor.php
@@ -603,6 +603,22 @@ class WP_HTML_Processor extends WP_HTML_Tag_Processor {
 		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.1 Refactored so subclasses may extend.
+	 *
+	 * @return bool Whether a token was parsed.
+	 */
+	public function next_token(): bool {
+		return $this->_next_token();
+	}
+
 	/**
 	 * Ensures internal accounting is maintained for HTML semantic rules while
 	 * the underlying Tag Processor class is seeking to a bookmark.
@@ -611,13 +627,13 @@ class WP_HTML_Processor extends WP_HTML_Tag_Processor {
 	 * 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.1 Added for internal support; do not use.
 	 *
 	 * @access private
 	 *
 	 * @return bool
 	 */
-	public function next_token(): bool {
+	private function _next_token(): bool {
 		$this->current_element = null;
 
 		if ( isset( $this->last_error ) ) {
@@ -635,7 +651,7 @@ class WP_HTML_Processor extends WP_HTML_Tag_Processor {
 		 *       tokens works in the meantime and isn't obviously wrong.
 		 */
 		if ( empty( $this->element_queue ) && $this->step() ) {
-			return $this->next_token();
+			return $this->_next_token();
 		}
 
 		// Process the next event on the queue.
@@ -646,7 +662,7 @@ class WP_HTML_Processor extends WP_HTML_Tag_Processor {
 				continue;
 			}
 
-			return empty( $this->element_queue ) ? false : $this->next_token();
+			return empty( $this->element_queue ) ? false : $this->_next_token();
 		}
 
 		$is_pop = WP_HTML_Stack_Event::POP === $this->current_element->operation;
@@ -657,7 +673,7 @@ class WP_HTML_Processor extends WP_HTML_Tag_Processor {
 		 * the breadcrumbs.
 		 */
 		if ( 'root-node' === $this->current_element->token->bookmark_name ) {
-			return $this->next_token();
+			return $this->_next_token();
 		}
 
 		// Adjust the breadcrumbs for this event.
@@ -669,7 +685,7 @@ class WP_HTML_Processor extends WP_HTML_Tag_Processor {
 
 		// 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_token();
 		}
 
 		return true;
diff --git a/wp-includes/version.php b/wp-includes/version.php
index 5e4574197a..b8b3e48beb 100644
--- a/wp-includes/version.php
+++ b/wp-includes/version.php
@@ -16,7 +16,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '6.8-alpha-59284';
+$wp_version = '6.8-alpha-59285';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.