<?php

/**

 * HTML API: WP_HTML_Processor class

 *

 * @package WordPress

 * @subpackage HTML-API

 * @since 6.4.0

 */

/**

 * Core class used to safely parse and modify an HTML document.

 *

 * The HTML Processor class properly parses and modifies HTML5 documents.

 *

 * It supports a subset of the HTML5 specification, and when it encounters

 * unsupported markup, it aborts early to avoid unintentionally breaking

 * the document. The HTML Processor should never break an HTML document.

 *

 * While the `WP_HTML_Tag_Processor` is a valuable tool for modifying

 * attributes on individual HTML tags, the HTML Processor is more capable

 * and useful for the following operations:

 *

 *  - Querying based on nested HTML structure.

 *

 * Eventually the HTML Processor will also support:

 *  - Wrapping a tag in surrounding HTML.

 *  - Unwrapping a tag by removing its parent.

 *  - Inserting and removing nodes.

 *  - Reading and changing inner content.

 *  - Navigating up or around HTML structure.

 *

 * ## Usage

 *

 * Use of this class requires three steps:

 *

 *   1. Call a static creator method with your input HTML document.

 *   2. Find the location in the document you are looking for.

 *   3. Request changes to the document at that location.

 *

 * Example:

 *

 *     $processor = WP_HTML_Processor::create_fragment( $html );

 *     if ( $processor->next_tag( array( 'breadcrumbs' => array( 'DIV', 'FIGURE', 'IMG' ) ) ) ) {

 *         $processor->add_class( 'responsive-image' );

 *     }

 *

 * #### Breadcrumbs

 *

 * Breadcrumbs represent the stack of open elements from the root

 * of the document or fragment down to the currently-matched node,

 * if one is currently selected. Call WP_HTML_Processor::get_breadcrumbs()

 * to inspect the breadcrumbs for a matched tag.

 *

 * Breadcrumbs can specify nested HTML structure and are equivalent

 * to a CSS selector comprising tag names separated by the child

 * combinator, such as "DIV > FIGURE > IMG".

 *

 * Since all elements find themselves inside a full HTML document

 * when parsed, the return value from `get_breadcrumbs()` will always

 * contain any implicit outermost elements. For example, when parsing

 * with `create_fragment()` in the `BODY` context (the default), any

 * tag in the given HTML document will contain `array( 'HTML', 'BODY', … )`

 * in its breadcrumbs.

 *

 * Despite containing the implied outermost elements in their breadcrumbs,

 * tags may be found with the shortest-matching breadcrumb query. That is,

 * `array( 'IMG' )` matches all IMG elements and `array( 'P', 'IMG' )`

 * matches all IMG elements directly inside a P element. To ensure that no

 * partial matches erroneously match it's possible to specify in a query

 * the full breadcrumb match all the way down from the root HTML element.

 *

 * Example:

 *

 *     $html = '<figure><img><figcaption>A <em>lovely</em> day outside</figcaption></figure>';

 *     //               ----- Matches here.

 *     $processor->next_tag( array( 'breadcrumbs' => array( 'FIGURE', 'IMG' ) ) );

 *

 *     $html = '<figure><img><figcaption>A <em>lovely</em> day outside</figcaption></figure>';

 *     //                                  ---- Matches here.

 *     $processor->next_tag( array( 'breadcrumbs' => array( 'FIGURE', 'FIGCAPTION', 'EM' ) ) );

 *

 *     $html = '<div><img></div><img>';

 *     //                       ----- Matches here, because IMG must be a direct child of the implicit BODY.

 *     $processor->next_tag( array( 'breadcrumbs' => array( 'BODY', 'IMG' ) ) );

 *

 * ## HTML Support

 *

 * This class implements a small part of the HTML5 specification.

 * It's designed to operate within its support and abort early whenever

 * encountering circumstances it can't properly handle. This is

 * the principle way in which this class remains as simple as possible

 * without cutting corners and breaking compliance.

 *

 * ### Supported elements

 *

 * If any unsupported element appears in the HTML input the HTML Processor

 * will abort early and stop all processing. This draconian measure ensures

 * that the HTML Processor won't break any HTML it doesn't fully understand.

 *

 * The following list specifies the HTML tags that _are_ supported:

 *

 *  - Containers: ADDRESS, BLOCKQUOTE, DETAILS, DIALOG, DIV, FOOTER, HEADER, MAIN, MENU, SPAN, SUMMARY.

 *  - Custom elements: All custom elements are supported. :)

 *  - Form elements: BUTTON, DATALIST, FIELDSET, INPUT, LABEL, LEGEND, METER, PROGRESS, SEARCH.

 *  - Formatting elements: B, BIG, CODE, EM, FONT, I, PRE, SMALL, STRIKE, STRONG, TT, U, WBR.

 *  - Heading elements: H1, H2, H3, H4, H5, H6, HGROUP.

 *  - Links: A.

 *  - Lists: DD, DL, DT, LI, OL, UL.

 *  - Media elements: AUDIO, CANVAS, EMBED, FIGCAPTION, FIGURE, IMG, MAP, PICTURE, SOURCE, TRACK, VIDEO.

 *  - Paragraph: BR, P.

 *  - Phrasing elements: ABBR, AREA, BDI, BDO, CITE, DATA, DEL, DFN, INS, MARK, OUTPUT, Q, SAMP, SUB, SUP, TIME, VAR.

 *  - Sectioning elements: ARTICLE, ASIDE, HR, NAV, SECTION.

 *  - Templating elements: SLOT.

 *  - Text decoration: RUBY.

 *  - Deprecated elements: ACRONYM, BLINK, CENTER, DIR, ISINDEX, KEYGEN, LISTING, MULTICOL, NEXTID, PARAM, SPACER.

 *

 * ### Supported markup

 *

 * Some kinds of non-normative HTML involve reconstruction of formatting elements and

 * re-parenting of mis-nested elements. For example, a DIV tag found inside a TABLE

 * may in fact belong _before_ the table in the DOM. If the HTML Processor encounters

 * such a case it will stop processing.

 *

 * The following list specifies HTML markup that _is_ supported:

 *

 *  - Markup involving only those tags listed above.

 *  - Fully-balanced and non-overlapping tags.

 *  - HTML with unexpected tag closers.

 *  - Some unbalanced or overlapping tags.

 *  - P tags after unclosed P tags.

 *  - BUTTON tags after unclosed BUTTON tags.

 *  - A tags after unclosed A tags that don't involve any active formatting elements.

 *

 * @since 6.4.0

 *

 * @see WP_HTML_Tag_Processor

 * @see https://html.spec.whatwg.org/

 */

class WP_HTML_Processor extends WP_HTML_Tag_Processor {

	/**

	 * The maximum number of bookmarks allowed to exist at any given time.

	 *

	 * HTML processing requires more bookmarks than basic tag processing,

	 * so this class constant from the Tag Processor is overwritten.

	 *

	 * @since 6.4.0

	 *

	 * @var int

	 */

	const MAX_BOOKMARKS = 100;

	/**

	 * Holds the working state of the parser, including the stack of

	 * open elements and the stack of active formatting elements.

	 *

	 * Initialized in the constructor.

	 *

	 * @since 6.4.0

	 *

	 * @var WP_HTML_Processor_State

	 */

	private $state = null;

	/**

	 * Used to create unique bookmark names.

	 *

	 * This class sets a bookmark for every tag in the HTML document that it encounters.

	 * The bookmark name is auto-generated and increments, starting with `1`. These are

	 * internal bookmarks and are automatically released when the referring WP_HTML_Token

	 * goes out of scope and is garbage-collected.

	 *

	 * @since 6.4.0

	 *

	 * @see WP_HTML_Processor::$release_internal_bookmark_on_destruct

	 *

	 * @var int

	 */

	private $bookmark_counter = 0;

	/**

	 * Stores an explanation for why something failed, if it did.

	 *

	 * @see self::get_last_error

	 *

	 * @since 6.4.0

	 *

	 * @var string|null

	 */

	private $last_error = null;

	/**

	 * Releases a bookmark when PHP garbage-collects its wrapping WP_HTML_Token instance.

	 *

	 * This function is created inside the class constructor so that it can be passed to

	 * the stack of open elements and the stack of active formatting elements without

	 * exposing it as a public method on the class.

	 *

	 * @since 6.4.0

	 *

	 * @var closure

	 */

	private $release_internal_bookmark_on_destruct = null;

	/**

	 * Stores stack events which arise during parsing of the

	 * HTML document, which will then supply the "match" events.

	 *

	 * @since 6.6.0

	 *

	 * @var WP_HTML_Stack_Event[]

	 */

	private $element_queue = array();

	/**

	 * Current stack event, if set, representing a matched token.

	 *

	 * Because the parser may internally point to a place further along in a document

	 * than the nodes which have already been processed (some "virtual" nodes may have

	 * appeared while scanning the HTML document), this will point at the "current" node

	 * being processed. It comes from the front of the element queue.

	 *

	 * @since 6.6.0

	 *

	 * @var ?WP_HTML_Stack_Event

	 */

	private $current_element = null;

	/**

	 * Context node if created as a fragment parser.

	 *

	 * @var ?WP_HTML_Token

	 */

	private $context_node = null;

	/**

	 * Whether the parser has yet processed the context node,

	 * if created as a fragment parser.

	 *

	 * The context node will be initially pushed onto the stack of open elements,

	 * but when created as a fragment parser, this context element (and the implicit

	 * HTML document node above it) should not be exposed as a matched token or node.

	 *

	 * This boolean indicates whether the processor should skip over the current

	 * node in its initial search for the first node created from the input HTML.

	 *

	 * @var bool

	 */

	private $has_seen_context_node = false;

	/*

	 * Public Interface Functions

	 */

	/**

	 * Creates an HTML processor in the fragment parsing mode.

	 *

	 * Use this for cases where you are processing chunks of HTML that

	 * will be found within a bigger HTML document, such as rendered

	 * block output that exists within a post, `the_content` inside a

	 * rendered site layout.

	 *

	 * Fragment parsing occurs within a context, which is an HTML element

	 * that the document will eventually be placed in. It becomes important

	 * when special elements have different rules than others, such as inside

	 * a TEXTAREA or a TITLE tag where things that look like tags are text,

	 * or inside a SCRIPT tag where things that look like HTML syntax are JS.

	 *

	 * The context value should be a representation of the tag into which the

	 * HTML is found. For most cases this will be the body element. The HTML

	 * form is provided because a context element may have attributes that

	 * impact the parse, such as with a SCRIPT tag and its `type` attribute.

	 *

	 * ## Current HTML Support

	 *

	 *  - The only supported context is `<body>`, which is the default value.

	 *  - The only supported document encoding is `UTF-8`, which is the default value.

	 *

	 * @since 6.4.0

	 * @since 6.6.0 Returns `static` instead of `self` so it can create subclass instances.

	 *

	 * @param string $html     Input HTML fragment to process.

	 * @param string $context  Context element for the fragment, must be default of `<body>`.

	 * @param string $encoding Text encoding of the document; must be default of 'UTF-8'.

	 * @return static|null The created processor if successful, otherwise null.

	 */

	public static function create_fragment( $html, $context = '<body>', $encoding = 'UTF-8' ) {

		if ( '<body>' !== $context || 'UTF-8' !== $encoding ) {

			return null;

		}

		$processor                        = new static( $html, self::CONSTRUCTOR_UNLOCK_CODE );

		$processor->state->context_node   = array( 'BODY', array() );

		$processor->state->insertion_mode = WP_HTML_Processor_State::INSERTION_MODE_IN_BODY;

		// @todo Create "fake" bookmarks for non-existent but implied nodes.

		$processor->bookmarks['root-node']    = new WP_HTML_Span( 0, 0 );

		$processor->bookmarks['context-node'] = new WP_HTML_Span( 0, 0 );

		$processor->state->stack_of_open_elements->push(

			new WP_HTML_Token(

				'root-node',

				'HTML',

				false

			)

		);

		$context_node = new WP_HTML_Token(

			'context-node',

			$processor->state->context_node[0],

			false

		);

		$processor->state->stack_of_open_elements->push( $context_node );

		$processor->context_node = $context_node;

		return $processor;

	}

	/**

	 * Constructor.

	 *

	 * Do not use this method. Use the static creator methods instead.

	 *

	 * @access private

	 *

	 * @since 6.4.0

	 *

	 * @see WP_HTML_Processor::create_fragment()

	 *

	 * @param string      $html                                  HTML to process.

	 * @param string|null $use_the_static_create_methods_instead This constructor should not be called manually.

	 */

	public function __construct( $html, $use_the_static_create_methods_instead = null ) {

		parent::__construct( $html );

		if ( self::CONSTRUCTOR_UNLOCK_CODE !== $use_the_static_create_methods_instead ) {

			_doing_it_wrong(

				__METHOD__,

				sprintf(

					/* translators: %s: WP_HTML_Processor::create_fragment(). */

					__( 'Call %s to create an HTML Processor instead of calling the constructor directly.' ),

					'<code>WP_HTML_Processor::create_fragment()</code>'

				),

				'6.4.0'

			);

		}

		$this->state = new WP_HTML_Processor_State();

		$this->state->stack_of_open_elements->set_push_handler(

			function ( WP_HTML_Token $token ) {

				$is_virtual            = ! isset( $this->state->current_token ) || $this->is_tag_closer();

				$same_node             = isset( $this->state->current_token ) && $token->node_name === $this->state->current_token->node_name;

				$provenance            = ( ! $same_node || $is_virtual ) ? 'virtual' : 'real';

				$this->element_queue[] = new WP_HTML_Stack_Event( $token, WP_HTML_Stack_Event::PUSH, $provenance );

			}

		);

		$this->state->stack_of_open_elements->set_pop_handler(

			function ( WP_HTML_Token $token ) {

				$is_virtual            = ! isset( $this->state->current_token ) || ! $this->is_tag_closer();

				$same_node             = isset( $this->state->current_token ) && $token->node_name === $this->state->current_token->node_name;

				$provenance            = ( ! $same_node || $is_virtual ) ? 'virtual' : 'real';

				$this->element_queue[] = new WP_HTML_Stack_Event( $token, WP_HTML_Stack_Event::POP, $provenance );

			}

		);

		/*

		 * Create this wrapper so that it's possible to pass

		 * a private method into WP_HTML_Token classes without

		 * exposing it to any public API.

		 */

		$this->release_internal_bookmark_on_destruct = function ( $name ) {

			parent::release_bookmark( $name );

		};

	}

	/**

	 * Returns the last error, if any.

	 *

	 * Various situations lead to parsing failure but this class will

	 * return `false` in all those cases. To determine why something

	 * failed it's possible to request the last error. This can be

	 * helpful to know to distinguish whether a given tag couldn't

	 * be found or if content in the document caused the processor

	 * to give up and abort processing.

	 *

	 * Example

	 *

	 *     $processor = WP_HTML_Processor::create_fragment( '<template><strong><button><em><p><em>' );

	 *     false === $processor->next_tag();

	 *     WP_HTML_Processor::ERROR_UNSUPPORTED === $processor->get_last_error();

	 *

	 * @since 6.4.0

	 *

	 * @see self::ERROR_UNSUPPORTED

	 * @see self::ERROR_EXCEEDED_MAX_BOOKMARKS

	 *

	 * @return string|null The last error, if one exists, otherwise null.

	 */

	public function get_last_error() {

		return $this->last_error;

	}

	/**

	 * Finds the next tag matching the $query.

	 *

	 * @todo Support matching the class name and tag name.

	 *

	 * @since 6.4.0

	 * @since 6.6.0 Visits all tokens, including virtual ones.

	 *

	 * @throws Exception When unable to allocate a bookmark for the next token in the input HTML document.

	 *

	 * @param array|string|null $query {

	 *     Optional. Which tag name to find, having which class, etc. Default is to find any tag.

	 *

	 *     @type string|null $tag_name     Which tag to find, or `null` for "any tag."

	 *     @type string      $tag_closers  'visit' to pause at tag closers, 'skip' or unset to only visit openers.

	 *     @type int|null    $match_offset Find the Nth tag matching all search criteria.

	 *                                     1 for "first" tag, 3 for "third," etc.

	 *                                     Defaults to first tag.

	 *     @type string|null $class_name   Tag must contain this whole class name to match.

	 *     @type string[]    $breadcrumbs  DOM sub-path at which element is found, e.g. `array( 'FIGURE', 'IMG' )`.

	 *                                     May also contain the wildcard `*` which matches a single element, e.g. `array( 'SECTION', '*' )`.

	 * }

	 * @return bool Whether a tag was matched.

	 */

	public function next_tag( $query = null ) {

		$visit_closers = isset( $query['tag_closers'] ) && 'visit' === $query['tag_closers'];

		if ( null === $query ) {

			while ( $this->next_token() ) {

				if ( '#tag' !== $this->get_token_type() ) {

					continue;

				}

				if ( ! $this->is_tag_closer() || $visit_closers ) {

					return true;

				}

			}

			return false;

		}

		if ( is_string( $query ) ) {

			$query = array( 'breadcrumbs' => array( $query ) );

		}

		if ( ! is_array( $query ) ) {

			_doing_it_wrong(

				__METHOD__,

				__( 'Please pass a query array to this function.' ),

				'6.4.0'

			);

			return false;

		}

		$needs_class = ( isset( $query['class_name'] ) && is_string( $query['class_name'] ) )

			? $query['class_name']

			: null;

		if ( ! ( array_key_exists( 'breadcrumbs', $query ) && is_array( $query['breadcrumbs'] ) ) ) {

			while ( $this->next_token() ) {

				if ( '#tag' !== $this->get_token_type() ) {