HTML API: Expand Unsupported class and make it available for debugging.

The HTML Processor internally throws an exception when it reaches HTML
that it knows it cannot process, but this exception is not made
available to calling code. It can be useful to extract more knowledge
about why it gave up, especially for debugging purposes.

In this patch, more context is added to the WP_HTML_Unsupported_Exception
and the last exception is made available to calling code, if it asks.

Author: dmsnell

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

@@ -188,6 +188,17 @@ class WP_HTML_Processor extends WP_HTML_Tag_Processor {
 	 */
 	private $last_error = null;
 
+	/**
+	 * Stores context for why the parser bailed on unsupported HTML, if it did.
+	 *
+	 * @see self::get_unsupported_exception
+	 *
+	 * @since 6.7.0
+	 *
+	 * @var WP_HTML_Unsupported_Exception|null
+	 */
+	private $unsupported_exception = null;
+
 	/**
 	 * Releases a bookmark when PHP garbage-collects its wrapping WP_HTML_Token instance.
 	 *
@@ -384,6 +395,45 @@ function ( WP_HTML_Token $token ) {
 		};
 	}
 
+	/**
+	 * Stops the parser and terminates its execution when encountering unsupported markup.
+	 *
+	 * @throws WP_HTML_Unsupported_Exception Halts execution of the parser.
+	 *
+	 * @since 6.7.0
+	 *
+	 * @param string $message Explains support is missing in order to parse the current node.
+	 *
+	 * @return mixed
+	 */
+	private function bail( string $message ) {
+		$here  = $this->bookmarks[ $this->state->current_token->bookmark_name ];
+		$token = substr( $this->html, $here->start, $here->length );
+
+		$open_elements = array();
+		foreach ( $this->state->stack_of_open_elements->stack as $item ) {
+			$open_elements[] = $item->node_name;
+		}
+
+		$active_formats = array();
+		foreach ( $this->state->active_formatting_elements->walk_down() as $item ) {
+			$active_formats[] = $item->node_name;
+		}
+
+		$this->last_error = self::ERROR_UNSUPPORTED;
+
+		$this->unsupported_exception = new WP_HTML_Unsupported_Exception(
+			$message,
+			$this->state->current_token->node_name,
+			$here->start,
+			$token,
+			$open_elements,
+			$active_formats
+		);
+
+		throw $this->unsupported_exception;
+	}
+
 	/**
 	 * Returns the last error, if any.
 	 *
@@ -411,6 +461,21 @@ public function get_last_error() {
 		return $this->last_error;
 	}
 
+	/**
+	 * Returns context for why the parser aborted due to unsupported HTML, if it did.
+	 *
+	 * This is meant for debugging purposes, not for production use.
+	 *
+	 * @since 6.7.0
+	 *
+	 * @see self::$unsupported_exception
+	 *
+	 * @return WP_HTML_Unsupported_Exception|null
+	 */
+	public function get_unsupported_exception() {
+		return $this->unsupported_exception;
+	}
+
 	/**
 	 * Finds the next tag matching the $query.
 	 *

src/wp-includes/html-api/class-wp-html-unsupported-exception.php

@@ -1,4 +1,4 @@
-<?php
+<?php declare( strict_types=1 );
 /**
  * HTML API: WP_HTML_Unsupported_Exception class
  *
@@ -27,5 +27,21 @@
  * @see WP_HTML_Processor
  */
 class WP_HTML_Unsupported_Exception extends Exception {
+	public $token_name;
+	public $token_at;
 
+	public $token;
+	public $stack_of_open_elements = array();
+	public $active_formatting_elements = array();
+
+	public function __construct( string $message, string $token_name, int $token_at, string $token, array $stack_of_open_elements, array $active_formatting_elements ) {
+		parent::__construct( $message );
+
+		$this->token_name = $token_name;
+		$this->token_at   = $token_at;
+		$this->token      = $token;
+
+		$this->stack_of_open_elements     = $stack_of_open_elements;
+		$this->active_formatting_elements = $active_formatting_elements;
+	}
 }