<?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.

 *

 *

 *

 * ### 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.

 *

 *

 *

 * @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

	 */

	/**

	 * 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

	 *

	 */

	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

	 *

	 */

	private $current_element = null;

	/**

	 * Context node if created as a fragment parser.

	 *

	 */

	private $context_node = null;

	/*

	 * 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;

		}

		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(

				$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(

				$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.

		 */

			parent::release_bookmark( $name );

		};

	}

	/**