1 <?php

     2 /**

     3  * HTML API: WP_HTML_Processor class

     4  *

     5  * @package WordPress

     6  * @subpackage HTML-API

     7  * @since 6.4.0

     8  */

     9 

    10 /**

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

    12  *

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

    14  *

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

    16  * unsupported markup, it aborts early to avoid unintentionally breaking

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

    18  *

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

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

    21  * and useful for the following operations:

    22  *

    23  *  - Querying based on nested HTML structure.

    24  *

    25  * Eventually the HTML Processor will also support:

    26  *  - Wrapping a tag in surrounding HTML.

    27  *  - Unwrapping a tag by removing its parent.

    28  *  - Inserting and removing nodes.

    29  *  - Reading and changing inner content.

    30  *  - Navigating up or around HTML structure.

    31  *

    32  * ## Usage

    33  *

    34  * Use of this class requires three steps:

    35  *

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

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

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

    39  *

    40  * Example:

    41  *

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

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

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

    45  *     }

    46  *

    47  * #### Breadcrumbs

    48  *

    49  * Breadcrumbs represent the stack of open elements from the root

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

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

    52  * to inspect the breadcrumbs for a matched tag.

    53  *

    54  * Breadcrumbs can specify nested HTML structure and are equivalent

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

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

    57  *

    58  * Since all elements find themselves inside a full HTML document

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

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

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

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

    63  * in its breadcrumbs.

    64  *

    65  * Despite containing the implied outermost elements in their breadcrumbs,

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

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

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

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

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

    71  *

    72  * Example:

    73  *

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

    75  *     //               ----- Matches here.

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

    77  *

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

    79  *     //                                  ---- Matches here.

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

    81  *

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

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

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

    85  *

    86  * ## HTML Support

    87  *

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

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

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

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

    92  * without cutting corners and breaking compliance.

    93  *

    94  * ### Supported elements

    95  *

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

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

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

    99  *

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

   101  *

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

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

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

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

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

   107  *  - Links: A.

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

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

   110  *  - Paragraph: BR, P.

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

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

   113  *  - Templating elements: SLOT.

   114  *  - Text decoration: RUBY.

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

   116  *

   117  * ### Supported markup

   118  *

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

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

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

   122  * such a case it will stop processing.

   123  *

   124  * The following list specifies HTML markup that _is_ supported:

   125  *

   126  *  - Markup involving only those tags listed above.

   127  *  - Fully-balanced and non-overlapping tags.

   128  *  - HTML with unexpected tag closers.

   129  *  - Some unbalanced or overlapping tags.

   130  *  - P tags after unclosed P tags.

   131  *  - BUTTON tags after unclosed BUTTON tags.

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

   133  *

   134  * @since 6.4.0

   135  *

   136  * @see WP_HTML_Tag_Processor

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

   138  */

   139 class WP_HTML_Processor extends WP_HTML_Tag_Processor {

   140 	/**

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

   142 	 *

   143 	 * HTML processing requires more bookmarks than basic tag processing,

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

   145 	 *

   146 	 * @since 6.4.0

   147 	 *

   148 	 * @var int

   149 	 */

   150 	const MAX_BOOKMARKS = 100;

   151 

   152 	/**

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

   154 	 * open elements and the stack of active formatting elements.

   155 	 *

   156 	 * Initialized in the constructor.

   157 	 *

   158 	 * @since 6.4.0

   159 	 *

   160 	 * @var WP_HTML_Processor_State

   161 	 */

   162 	private $state = null;

   163 

   164 	/**

   165 	 * Used to create unique bookmark names.

   166 	 *

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

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

   169 	 * internal bookmarks and are automatically released when the referring WP_HTML_Token

   170 	 * goes out of scope and is garbage-collected.

   171 	 *

   172 	 * @since 6.4.0

   173 	 *

   174 	 * @see WP_HTML_Processor::$release_internal_bookmark_on_destruct

   175 	 *

   176 	 * @var int

   177 	 */

   178 	private $bookmark_counter = 0;

   179 

   180 	/**

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

   182 	 *

   183 	 * @see self::get_last_error

   184 	 *

   185 	 * @since 6.4.0

   186 	 *

   187 	 * @var string|null

   188 	 */

   189 	private $last_error = null;

   190 

   191 	/**

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

   193 	 *

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

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

   196 	 * exposing it as a public method on the class.

   197 	 *

   198 	 * @since 6.4.0

   199 	 *

   200 	 * @var closure

   201 	 */

   202 	private $release_internal_bookmark_on_destruct = null;

   203 

   204 	/**

   205 	 * Stores stack events which arise during parsing of the

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

   207 	 *

   208 	 * @since 6.6.0

   209 	 *

   210 	 * @var WP_HTML_Stack_Event[]

   211 	 */

   212 	private $element_queue = array();

   213 

   214 	/**

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

   216 	 *

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

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

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

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

   221 	 *

   222 	 * @since 6.6.0

   223 	 *

   224 	 * @var ?WP_HTML_Stack_Event

   225 	 */

   226 	private $current_element = null;

   227 

   228 	/**

   229 	 * Context node if created as a fragment parser.

   230 	 *

   231 	 * @var ?WP_HTML_Token

   232 	 */

   233 	private $context_node = null;

   234 

   235 	/**

   236 	 * Whether the parser has yet processed the context node,

   237 	 * if created as a fragment parser.

   238 	 *

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

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

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

   242 	 *

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

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

   245 	 *

   246 	 * @var bool

   247 	 */

   248 	private $has_seen_context_node = false;

   249 

   250 	/*

   251 	 * Public Interface Functions

   252 	 */

   253 

   254 	/**

   255 	 * Creates an HTML processor in the fragment parsing mode.

   256 	 *

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

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

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

   260 	 * rendered site layout.

   261 	 *

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

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

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

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

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

   267 	 *

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

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

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

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

   272 	 *

   273 	 * ## Current HTML Support

   274 	 *

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

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

   277 	 *

   278 	 * @since 6.4.0

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

   280 	 *

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

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

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

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

   285 	 */

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

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

   288 			return null;

   289 		}

   290 

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

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

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

   294 

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

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

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

   298 

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

   300 			new WP_HTML_Token(

   301 				'root-node',

   302 				'HTML',

   303 				false

   304 			)

   305 		);

   306 

   307 		$context_node = new WP_HTML_Token(

   308 			'context-node',

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

   310 			false

   311 		);

   312 

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

   314 		$processor->context_node = $context_node;

   315 

   316 		return $processor;

   317 	}

   318 

   319 	/**

   320 	 * Constructor.

   321 	 *

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

   323 	 *

   324 	 * @access private

   325 	 *

   326 	 * @since 6.4.0

   327 	 *

   328 	 * @see WP_HTML_Processor::create_fragment()

   329 	 *

   330 	 * @param string      $html                                  HTML to process.

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

   332 	 */

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

   334 		parent::__construct( $html );

   335 

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

   337 			_doing_it_wrong(

   338 				__METHOD__,

   339 				sprintf(

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

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

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

   343 				),

   344 				'6.4.0'

   345 			);

   346 		}

   347 

   348 		$this->state = new WP_HTML_Processor_State();

   349 

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

   351 			function ( WP_HTML_Token $token ) {

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

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

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

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

   356 			}

   357 		);

   358 

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

   360 			function ( WP_HTML_Token $token ) {

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

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

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

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

   365 			}

   366 		);

   367 

   368 		/*

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

   370 		 * a private method into WP_HTML_Token classes without

   371 		 * exposing it to any public API.

   372 		 */

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

   374 			parent::release_bookmark( $name );

   375 		};

   376 	}

   377 

   378 	/**

   379 	 * Returns the last error, if any.

   380 	 *

   381 	 * Various situations lead to parsing failure but this class will

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

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

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

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

   386 	 * to give up and abort processing.

   387 	 *

   388 	 * Example

   389 	 *

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

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

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

   393 	 *

   394 	 * @since 6.4.0

   395 	 *

   396 	 * @see self::ERROR_UNSUPPORTED

   397 	 * @see self::ERROR_EXCEEDED_MAX_BOOKMARKS

   398 	 *

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

   400 	 */

   401 	public function get_last_error() {

   402 		return $this->last_error;

   403 	}

   404 

   405 	/**

   406 	 * Finds the next tag matching the $query.

   407 	 *

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

   409 	 *

   410 	 * @since 6.4.0

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

   412 	 *

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

   414 	 *

   415 	 * @param array|string|null $query {

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

   417 	 *

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

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

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

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

   422 	 *                                     Defaults to first tag.

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

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

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

   426 	 * }

   427 	 * @return bool Whether a tag was matched.

   428 	 */

   429 	public function next_tag( $query = null ) {

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

   431 

   432 		if ( null === $query ) {

   433 			while ( $this->next_token() ) {

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

   435 					continue;

   436 				}

   437 

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

   439 					return true;

   440 				}

   441 			}

   442 

   443 			return false;

   444 		}

   445 

   446 		if ( is_string( $query ) ) {

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

   448 		}

   449 

   450 		if ( ! is_array( $query ) ) {

   451 			_doing_it_wrong(

   452 				__METHOD__,

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

   454 				'6.4.0'

   455 			);

   456 			return false;

   457 		}

   458 

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

   460 			? $query['class_name']

   461 			: null;

   462 

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

   464 			while ( $this->next_token() ) {

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

   466 					continue;

   467 				}

   468 

   469 				if ( isset( $needs_class ) && ! $this->has_class( $needs_class ) ) {

   470 					continue;

   471 				}

   472 

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

   474 					return true;

   475 				}

   476 			}

   477 

   478 			return false;

   479 		}

   480 

   481 		$breadcrumbs  = $query['breadcrumbs'];

   482 		$match_offset = isset( $query['match_offset'] ) ? (int) $query['match_offset'] : 1;

   483 

   484 		while ( $match_offset > 0 && $this->next_token() ) {

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

   486 				continue;

   487 			}

   488 

   489 			if ( isset( $needs_class ) && ! $this->has_class( $needs_class ) ) {

   490 				continue;

   491 			}

   492 

   493 			if ( $this->matches_breadcrumbs( $breadcrumbs ) && 0 === --$match_offset ) {

   494 				return true;

   495 			}

   496 		}

   497 

   498 		return false;

   499 	}

   500 

   501 	/**

   502 	 * Ensures internal accounting is maintained for HTML semantic rules while

   503 	 * the underlying Tag Processor class is seeking to a bookmark.

   504 	 *

   505 	 * This doesn't currently have a way to represent non-tags and doesn't process

   506 	 * semantic rules for text nodes. For access to the raw tokens consider using

   507 	 * WP_HTML_Tag_Processor instead.

   508 	 *

   509 	 * @since 6.5.0 Added for internal support; do not use.

   510 	 *

   511 	 * @access private

   512 	 *

   513 	 * @return bool

   514 	 */

   515 	public function next_token() {

   516 		$this->current_element = null;

   517 

   518 		if ( isset( $this->last_error ) ) {

   519 			return false;

   520 		}

   521 

   522 		if ( 'done' !== $this->has_seen_context_node && 0 === count( $this->element_queue ) && ! $this->step() ) {

   523 			while ( 'context-node' !== $this->state->stack_of_open_elements->current_node()->bookmark_name && $this->state->stack_of_open_elements->pop() ) {

   524 				continue;

   525 			}

   526 			$this->has_seen_context_node = 'done';

   527 			return $this->next_token();

   528 		}

   529 

   530 		$this->current_element = array_shift( $this->element_queue );

   531 		while ( isset( $this->context_node ) && ! $this->has_seen_context_node ) {

   532 			if ( isset( $this->current_element ) ) {

   533 				if ( $this->context_node === $this->current_element->token && WP_HTML_Stack_Event::PUSH === $this->current_element->operation ) {

   534 					$this->has_seen_context_node = true;

   535 					return $this->next_token();

   536 				}

   537 			}

   538 			$this->current_element = array_shift( $this->element_queue );

   539 		}

   540 

   541 		if ( ! isset( $this->current_element ) ) {

   542 			if ( 'done' === $this->has_seen_context_node ) {

   543 				return false;

   544 			} else {

   545 				return $this->next_token();

   546 			}

   547 		}

   548 

   549 		if ( isset( $this->context_node ) && WP_HTML_Stack_Event::POP === $this->current_element->operation && $this->context_node === $this->current_element->token ) {

   550 			$this->element_queue   = array();

   551 			$this->current_element = null;

   552 			return false;

   553 		}

   554 

   555 		// Avoid sending close events for elements which don't expect a closing.

   556 		if (

   557 			WP_HTML_Stack_Event::POP === $this->current_element->operation &&

   558 			! static::expects_closer( $this->current_element->token )

   559 		) {

   560 			return $this->next_token();

   561 		}

   562 

   563 		return true;

   564 	}

   565 

   566 

   567 	/**

   568 	 * Indicates if the current tag token is a tag closer.

   569 	 *

   570 	 * Example:

   571 	 *

   572 	 *     $p = WP_HTML_Processor::create_fragment( '<div></div>' );

   573 	 *     $p->next_tag( array( 'tag_name' => 'div', 'tag_closers' => 'visit' ) );

   574 	 *     $p->is_tag_closer() === false;

   575 	 *

   576 	 *     $p->next_tag( array( 'tag_name' => 'div', 'tag_closers' => 'visit' ) );

   577 	 *     $p->is_tag_closer() === true;

   578 	 *

   579 	 * @since 6.6.0 Subclassed for HTML Processor.

   580 	 *

   581 	 * @return bool Whether the current tag is a tag closer.

   582 	 */

   583 	public function is_tag_closer() {

   584 		return $this->is_virtual()

   585 			? ( WP_HTML_Stack_Event::POP === $this->current_element->operation && '#tag' === $this->get_token_type() )

   586 			: parent::is_tag_closer();

   587 	}

   588 

   589 	/**

   590 	 * Indicates if the currently-matched token is virtual, created by a stack operation

   591 	 * while processing HTML, rather than a token found in the HTML text itself.

   592 	 *

   593 	 * @since 6.6.0

   594 	 *

   595 	 * @return bool Whether the current token is virtual.

   596 	 */

   597 	private function is_virtual() {

   598 		return (

   599 			isset( $this->current_element->provenance ) &&

   600 			'virtual' === $this->current_element->provenance

   601 		);

   602 	}

   603 

   604 	/**

   605 	 * Indicates if the currently-matched tag matches the given breadcrumbs.

   606 	 *

   607 	 * A "*" represents a single tag wildcard, where any tag matches, but not no tags.

   608 	 *

   609 	 * At some point this function _may_ support a `**` syntax for matching any number

   610 	 * of unspecified tags in the breadcrumb stack. This has been intentionally left

   611 	 * out, however, to keep this function simple and to avoid introducing backtracking,

   612 	 * which could open up surprising performance breakdowns.

   613 	 *

   614 	 * Example:

   615 	 *

   616 	 *     $processor = WP_HTML_Processor::create_fragment( '<div><span><figure><img></figure></span></div>' );

   617 	 *     $processor->next_tag( 'img' );

   618 	 *     true  === $processor->matches_breadcrumbs( array( 'figure', 'img' ) );

   619 	 *     true  === $processor->matches_breadcrumbs( array( 'span', 'figure', 'img' ) );

   620 	 *     false === $processor->matches_breadcrumbs( array( 'span', 'img' ) );

   621 	 *     true  === $processor->matches_breadcrumbs( array( 'span', '*', 'img' ) );

   622 	 *

   623 	 * @since 6.4.0

   624 	 *

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

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

   627 	 * @return bool Whether the currently-matched tag is found at the given nested structure.

   628 	 */

   629 	public function matches_breadcrumbs( $breadcrumbs ) {

   630 		// Everything matches when there are zero constraints.

   631 		if ( 0 === count( $breadcrumbs ) ) {

   632 			return true;

   633 		}

   634 

   635 		// Start at the last crumb.

   636 		$crumb = end( $breadcrumbs );

   637 

   638 		if ( '*' !== $crumb && $this->get_tag() !== strtoupper( $crumb ) ) {

   639 			return false;

   640 		}

   641 

   642 		foreach ( $this->state->stack_of_open_elements->walk_up() as $node ) {

   643 			$crumb = strtoupper( current( $breadcrumbs ) );

   644 

   645 			if ( '*' !== $crumb && $node->node_name !== $crumb ) {

   646 				return false;

   647 			}

   648 

   649 			if ( false === prev( $breadcrumbs ) ) {

   650 				return true;

   651 			}

   652 		}

   653 

   654 		return false;

   655 	}

   656 

   657 	/**

   658 	 * Indicates if the currently-matched node expects a closing

   659 	 * token, or if it will self-close on the next step.

   660 	 *

   661 	 * Most HTML elements expect a closer, such as a P element or

   662 	 * a DIV element. Others, like an IMG element are void and don't

   663 	 * have a closing tag. Special elements, such as SCRIPT and STYLE,

   664 	 * are treated just like void tags. Text nodes and self-closing

   665 	 * foreign content will also act just like a void tag, immediately

   666 	 * closing as soon as the processor advances to the next token.

   667 	 *

   668 	 * @since 6.6.0

   669 	 *

   670 	 * @todo When adding support for foreign content, ensure that

   671 	 *       this returns false for self-closing elements in the

   672 	 *       SVG and MathML namespace.

   673 	 *

   674 	 * @param  ?WP_HTML_Token $node Node to examine instead of current node, if provided.

   675 	 * @return bool Whether to expect a closer for the currently-matched node,

   676 	 *              or `null` if not matched on any token.

   677 	 */

   678 	public function expects_closer( $node = null ) {

   679 		$token_name = $node->node_name ?? $this->get_token_name();

   680 		if ( ! isset( $token_name ) ) {

   681 			return null;

   682 		}

   683 

   684 		return ! (

   685 			// Comments, text nodes, and other atomic tokens.

   686 			'#' === $token_name[0] ||

   687 			// Doctype declarations.

   688 			'html' === $token_name ||

   689 			// Void elements.

   690 			self::is_void( $token_name ) ||

   691 			// Special atomic elements.

   692 			in_array( $token_name, array( 'IFRAME', 'NOEMBED', 'NOFRAMES', 'SCRIPT', 'STYLE', 'TEXTAREA', 'TITLE', 'XMP' ), true )

   693 		);

   694 	}

   695 

   696 	/**

   697 	 * Steps through the HTML document and stop at the next tag, if any.

   698 	 *

   699 	 * @since 6.4.0

   700 	 *

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

   702 	 *

   703 	 * @see self::PROCESS_NEXT_NODE

   704 	 * @see self::REPROCESS_CURRENT_NODE

   705 	 *

   706 	 * @param string $node_to_process Whether to parse the next node or reprocess the current node.

   707 	 * @return bool Whether a tag was matched.

   708 	 */

   709 	public function step( $node_to_process = self::PROCESS_NEXT_NODE ) {

   710 		// Refuse to proceed if there was a previous error.

   711 		if ( null !== $this->last_error ) {

   712 			return false;

   713 		}

   714 

   715 		if ( self::REPROCESS_CURRENT_NODE !== $node_to_process ) {

   716 			/*

   717 			 * Void elements still hop onto the stack of open elements even though

   718 			 * there's no corresponding closing tag. This is important for managing

   719 			 * stack-based operations such as "navigate to parent node" or checking

   720 			 * on an element's breadcrumbs.

   721 			 *

   722 			 * When moving on to the next node, therefore, if the bottom-most element

   723 			 * on the stack is a void element, it must be closed.

   724 			 *

   725 			 * @todo Once self-closing foreign elements and BGSOUND are supported,

   726 			 *        they must also be implicitly closed here too. BGSOUND is

   727 			 *        special since it's only self-closing if the self-closing flag

   728 			 *        is provided in the opening tag, otherwise it expects a tag closer.

   729 			 */

   730 			$top_node = $this->state->stack_of_open_elements->current_node();

   731 			if ( isset( $top_node ) && ! static::expects_closer( $top_node ) ) {

   732 				$this->state->stack_of_open_elements->pop();

   733 			}

   734 		}

   735 

   736 		if ( self::PROCESS_NEXT_NODE === $node_to_process ) {

   737 			parent::next_token();

   738 		}

   739 

   740 		// Finish stepping when there are no more tokens in the document.

   741 		if (

   742 			WP_HTML_Tag_Processor::STATE_INCOMPLETE_INPUT === $this->parser_state ||

   743 			WP_HTML_Tag_Processor::STATE_COMPLETE === $this->parser_state

   744 		) {

   745 			return false;

   746 		}

   747 

   748 		$this->state->current_token = new WP_HTML_Token(

   749 			$this->bookmark_token(),

   750 			$this->get_token_name(),

   751 			$this->has_self_closing_flag(),

   752 			$this->release_internal_bookmark_on_destruct

   753 		);

   754 

   755 		try {

   756 			switch ( $this->state->insertion_mode ) {

   757 				case WP_HTML_Processor_State::INSERTION_MODE_IN_BODY:

   758 					return $this->step_in_body();

   759 

   760 				default:

   761 					$this->last_error = self::ERROR_UNSUPPORTED;

   762 					throw new WP_HTML_Unsupported_Exception( "No support for parsing in the '{$this->state->insertion_mode}' state." );

   763 			}

   764 		} catch ( WP_HTML_Unsupported_Exception $e ) {

   765 			/*

   766 			 * Exceptions are used in this class to escape deep call stacks that

   767 			 * otherwise might involve messier calling and return conventions.

   768 			 */

   769 			return false;

   770 		}

   771 	}

   772 

   773 	/**

   774 	 * Computes the HTML breadcrumbs for the currently-matched node, if matched.

   775 	 *

   776 	 * Breadcrumbs start at the outermost parent and descend toward the matched element.

   777 	 * They always include the entire path from the root HTML node to the matched element.

   778 	 *

   779 	 * @todo It could be more efficient to expose a generator-based version of this function

   780 	 *       to avoid creating the array copy on tag iteration. If this is done, it would likely

   781 	 *       be more useful to walk up the stack when yielding instead of starting at the top.

   782 	 *

   783 	 * Example

   784 	 *

   785 	 *     $processor = WP_HTML_Processor::create_fragment( '<p><strong><em><img></em></strong></p>' );

   786 	 *     $processor->next_tag( 'IMG' );

   787 	 *     $processor->get_breadcrumbs() === array( 'HTML', 'BODY', 'P', 'STRONG', 'EM', 'IMG' );

   788 	 *

   789 	 * @since 6.4.0

   790 	 *

   791 	 * @return string[]|null Array of tag names representing path to matched node, if matched, otherwise NULL.

   792 	 */

   793 	public function get_breadcrumbs() {

   794 		$breadcrumbs = array();

   795 

   796 		foreach ( $this->state->stack_of_open_elements->walk_down() as $stack_item ) {

   797 			$breadcrumbs[] = $stack_item->node_name;

   798 		}

   799 

   800 		if ( ! $this->is_virtual() ) {

   801 			return $breadcrumbs;

   802 		}

   803 

   804 		foreach ( $this->element_queue as $queue_item ) {

   805 			if ( $this->current_element->token->bookmark_name === $queue_item->token->bookmark_name ) {

   806 				break;

   807 			}

   808 

   809 			if ( 'context-node' === $queue_item->token->bookmark_name ) {

   810 				break;

   811 			}

   812 

   813 			if ( 'real' === $queue_item->provenance ) {

   814 				break;

   815 			}

   816 

   817 			if ( WP_HTML_Stack_Event::PUSH === $queue_item->operation ) {

   818 				$breadcrumbs[] = $queue_item->token->node_name;

   819 			} else {

   820 				array_pop( $breadcrumbs );

   821 			}

   822 		}

   823 

   824 		if ( null !== parent::get_token_name() && ! parent::is_tag_closer() ) {

   825 			array_pop( $breadcrumbs );

   826 		}

   827 

   828 		// Add the virtual node we're at.

   829 		if ( WP_HTML_Stack_Event::PUSH === $this->current_element->operation ) {

   830 			$breadcrumbs[] = $this->current_element->token->node_name;

   831 		}

   832 

   833 		return $breadcrumbs;

   834 	}

   835 

   836 	/**

   837 	 * Returns the nesting depth of the current location in the document.

   838 	 *

   839 	 * Example:

   840 	 *

   841 	 *     $processor = WP_HTML_Processor::create_fragment( '<div><p></p></div>' );

   842 	 *     // The processor starts in the BODY context, meaning it has depth from the start: HTML > BODY.

   843 	 *     2 === $processor->get_current_depth();

   844 	 *

   845 	 *     // Opening the DIV element increases the depth.

   846 	 *     $processor->next_token();

   847 	 *     3 === $processor->get_current_depth();

   848 	 *

   849 	 *     // Opening the P element increases the depth.

   850 	 *     $processor->next_token();

   851 	 *     4 === $processor->get_current_depth();

   852 	 *

   853 	 *     // The P element is closed during `next_token()` so the depth is decreased to reflect that.

   854 	 *     $processor->next_token();

   855 	 *     3 === $processor->get_current_depth();

   856 	 *

   857 	 * @since 6.6.0

   858 	 *

   859 	 * @return int Nesting-depth of current location in the document.

   860 	 */

   861 	public function get_current_depth() {

   862 		return $this->is_virtual()

   863 			? count( $this->get_breadcrumbs() )

   864 			: $this->state->stack_of_open_elements->count();

   865 	}

   866 

   867 	/**

   868 	 * Parses next element in the 'in body' insertion mode.

   869 	 *

   870 	 * This internal function performs the 'in body' insertion mode

   871 	 * logic for the generalized WP_HTML_Processor::step() function.

   872 	 *

   873 	 * @since 6.4.0

   874 	 *

   875 	 * @throws WP_HTML_Unsupported_Exception When encountering unsupported HTML input.

   876 	 *

   877 	 * @see https://html.spec.whatwg.org/#parsing-main-inbody

   878 	 * @see WP_HTML_Processor::step

   879 	 *

   880 	 * @return bool Whether an element was found.

   881 	 */

   882 	private function step_in_body() {

   883 		$token_name = $this->get_token_name();

   884 		$token_type = $this->get_token_type();

   885 		$op_sigil   = '#tag' === $token_type ? ( parent::is_tag_closer() ? '-' : '+' ) : '';

   886 		$op         = "{$op_sigil}{$token_name}";

   887 

   888 		switch ( $op ) {

   889 			case '#comment':

   890 			case '#funky-comment':

   891 			case '#presumptuous-tag':

   892 				$this->insert_html_element( $this->state->current_token );

   893 				return true;

   894 

   895 			case '#text':

   896 				$this->reconstruct_active_formatting_elements();

   897 

   898 				$current_token = $this->bookmarks[ $this->state->current_token->bookmark_name ];

   899 

   900 				/*

   901 				 * > A character token that is U+0000 NULL

   902 				 *

   903 				 * Any successive sequence of NULL bytes is ignored and won't

   904 				 * trigger active format reconstruction. Therefore, if the text

   905 				 * only comprises NULL bytes then the token should be ignored

   906 				 * here, but if there are any other characters in the stream

   907 				 * the active formats should be reconstructed.

   908 				 */

   909 				if (

   910 					1 <= $current_token->length &&

   911 					"\x00" === $this->html[ $current_token->start ] &&

   912 					strspn( $this->html, "\x00", $current_token->start, $current_token->length ) === $current_token->length

   913 				) {

   914 					// Parse error: ignore the token.

   915 					return $this->step();

   916 				}

   917 

   918 				/*

   919 				 * Whitespace-only text does not affect the frameset-ok flag.

   920 				 * It is probably inter-element whitespace, but it may also

   921 				 * contain character references which decode only to whitespace.

   922 				 */

   923 				$text = $this->get_modifiable_text();

   924 				if ( strlen( $text ) !== strspn( $text, " \t\n\f\r" ) ) {

   925 					$this->state->frameset_ok = false;

   926 				}

   927 

   928 				$this->insert_html_element( $this->state->current_token );

   929 				return true;

   930 

   931 			case 'html':

   932 				/*

   933 				 * > A DOCTYPE token

   934 				 * > Parse error. Ignore the token.

   935 				 */

   936 				return $this->step();

   937 

   938 			/*

   939 			 * > A start tag whose tag name is "button"

   940 			 */

   941 			case '+BUTTON':

   942 				if ( $this->state->stack_of_open_elements->has_element_in_scope( 'BUTTON' ) ) {

   943 					// @todo Indicate a parse error once it's possible. This error does not impact the logic here.

   944 					$this->generate_implied_end_tags();

   945 					$this->state->stack_of_open_elements->pop_until( 'BUTTON' );

   946 				}

   947 

   948 				$this->reconstruct_active_formatting_elements();

   949 				$this->insert_html_element( $this->state->current_token );

   950 				$this->state->frameset_ok = false;

   951 

   952 				return true;

   953 

   954 			/*

   955 			 * > A start tag whose tag name is one of: "address", "article", "aside",

   956 			 * > "blockquote", "center", "details", "dialog", "dir", "div", "dl",

   957 			 * > "fieldset", "figcaption", "figure", "footer", "header", "hgroup",

   958 			 * > "main", "menu", "nav", "ol", "p", "search", "section", "summary", "ul"

   959 			 */

   960 			case '+ADDRESS':

   961 			case '+ARTICLE':

   962 			case '+ASIDE':

   963 			case '+BLOCKQUOTE':

   964 			case '+CENTER':

   965 			case '+DETAILS':

   966 			case '+DIALOG':

   967 			case '+DIR':

   968 			case '+DIV':

   969 			case '+DL':

   970 			case '+FIELDSET':

   971 			case '+FIGCAPTION':

   972 			case '+FIGURE':

   973 			case '+FOOTER':

   974 			case '+HEADER':

   975 			case '+HGROUP':

   976 			case '+MAIN':

   977 			case '+MENU':

   978 			case '+NAV':

   979 			case '+OL':

   980 			case '+P':

   981 			case '+SEARCH':

   982 			case '+SECTION':

   983 			case '+SUMMARY':

   984 			case '+UL':

   985 				if ( $this->state->stack_of_open_elements->has_p_in_button_scope() ) {

   986 					$this->close_a_p_element();

   987 				}

   988 

   989 				$this->insert_html_element( $this->state->current_token );

   990 				return true;

   991 

   992 			/*

   993 			 * > An end tag whose tag name is one of: "address", "article", "aside", "blockquote",

   994 			 * > "button", "center", "details", "dialog", "dir", "div", "dl", "fieldset",

   995 			 * > "figcaption", "figure", "footer", "header", "hgroup", "listing", "main",

   996 			 * > "menu", "nav", "ol", "pre", "search", "section", "summary", "ul"

   997 			 */

   998 			case '-ADDRESS':

   999 			case '-ARTICLE':

  1000 			case '-ASIDE':

  1001 			case '-BLOCKQUOTE':

  1002 			case '-BUTTON':

  1003 			case '-CENTER':

  1004 			case '-DETAILS':

  1005 			case '-DIALOG':

  1006 			case '-DIR':

  1007 			case '-DIV':

  1008 			case '-DL':

  1009 			case '-FIELDSET':

  1010 			case '-FIGCAPTION':

  1011 			case '-FIGURE':

  1012 			case '-FOOTER':

  1013 			case '-HEADER':

  1014 			case '-HGROUP':

  1015 			case '-LISTING':

  1016 			case '-MAIN':

  1017 			case '-MENU':

  1018 			case '-NAV':

  1019 			case '-OL':

  1020 			case '-PRE':

  1021 			case '-SEARCH':

  1022 			case '-SECTION':

  1023 			case '-SUMMARY':

  1024 			case '-UL':

  1025 				if ( ! $this->state->stack_of_open_elements->has_element_in_scope( $token_name ) ) {

  1026 					// @todo Report parse error.

  1027 					// Ignore the token.

  1028 					return $this->step();

  1029 				}

  1030 

  1031 				$this->generate_implied_end_tags();

  1032 				if ( $this->state->stack_of_open_elements->current_node()->node_name !== $token_name ) {

  1033 					// @todo Record parse error: this error doesn't impact parsing.

  1034 				}

  1035 				$this->state->stack_of_open_elements->pop_until( $token_name );

  1036 				return true;

  1037 

  1038 			/*

  1039 			 * > A start tag whose tag name is one of: "h1", "h2", "h3", "h4", "h5", "h6"

  1040 			 */

  1041 			case '+H1':

  1042 			case '+H2':

  1043 			case '+H3':

  1044 			case '+H4':

  1045 			case '+H5':

  1046 			case '+H6':

  1047 				if ( $this->state->stack_of_open_elements->has_p_in_button_scope() ) {

  1048 					$this->close_a_p_element();

  1049 				}

  1050 

  1051 				if (

  1052 					in_array(

  1053 						$this->state->stack_of_open_elements->current_node()->node_name,

  1054 						array( 'H1', 'H2', 'H3', 'H4', 'H5', 'H6' ),

  1055 						true

  1056 					)

  1057 				) {

  1058 					// @todo Indicate a parse error once it's possible.

  1059 					$this->state->stack_of_open_elements->pop();

  1060 				}

  1061 

  1062 				$this->insert_html_element( $this->state->current_token );

  1063 				return true;

  1064 

  1065 			/*

  1066 			 * > A start tag whose tag name is one of: "pre", "listing"

  1067 			 */

  1068 			case '+PRE':

  1069 			case '+LISTING':

  1070 				if ( $this->state->stack_of_open_elements->has_p_in_button_scope() ) {

  1071 					$this->close_a_p_element();

  1072 				}

  1073 				$this->insert_html_element( $this->state->current_token );

  1074 				$this->state->frameset_ok = false;

  1075 				return true;

  1076 

  1077 			/*

  1078 			 * > An end tag whose tag name is one of: "h1", "h2", "h3", "h4", "h5", "h6"

  1079 			 */

  1080 			case '-H1':

  1081 			case '-H2':

  1082 			case '-H3':

  1083 			case '-H4':

  1084 			case '-H5':

  1085 			case '-H6':

  1086 				if ( ! $this->state->stack_of_open_elements->has_element_in_scope( '(internal: H1 through H6 - do not use)' ) ) {

  1087 					/*

  1088 					 * This is a parse error; ignore the token.

  1089 					 *

  1090 					 * @todo Indicate a parse error once it's possible.

  1091 					 */

  1092 					return $this->step();

  1093 				}

  1094 

  1095 				$this->generate_implied_end_tags();

  1096 

  1097 				if ( $this->state->stack_of_open_elements->current_node()->node_name !== $token_name ) {

  1098 					// @todo Record parse error: this error doesn't impact parsing.

  1099 				}

  1100 

  1101 				$this->state->stack_of_open_elements->pop_until( '(internal: H1 through H6 - do not use)' );

  1102 				return true;

  1103 

  1104 			/*

  1105 			 * > A start tag whose tag name is "li"

  1106 			 * > A start tag whose tag name is one of: "dd", "dt"

  1107 			 */

  1108 			case '+DD':

  1109 			case '+DT':

  1110 			case '+LI':

  1111 				$this->state->frameset_ok = false;

  1112 				$node                     = $this->state->stack_of_open_elements->current_node();

  1113 				$is_li                    = 'LI' === $token_name;

  1114 

  1115 				in_body_list_loop:

  1116 				/*

  1117 				 * The logic for LI and DT/DD is the same except for one point: LI elements _only_

  1118 				 * close other LI elements, but a DT or DD element closes _any_ open DT or DD element.

  1119 				 */

  1120 				if ( $is_li ? 'LI' === $node->node_name : ( 'DD' === $node->node_name || 'DT' === $node->node_name ) ) {

  1121 					$node_name = $is_li ? 'LI' : $node->node_name;

  1122 					$this->generate_implied_end_tags( $node_name );

  1123 					if ( $node_name !== $this->state->stack_of_open_elements->current_node()->node_name ) {

  1124 						// @todo Indicate a parse error once it's possible. This error does not impact the logic here.

  1125 					}

  1126 

  1127 					$this->state->stack_of_open_elements->pop_until( $node_name );

  1128 					goto in_body_list_done;

  1129 				}

  1130 

  1131 				if (

  1132 					'ADDRESS' !== $node->node_name &&

  1133 					'DIV' !== $node->node_name &&

  1134 					'P' !== $node->node_name &&

  1135 					$this->is_special( $node->node_name )