wppaste
WordPress

WP_HTML_Processor

Since
6.4.0
Source
wp-includes/html-api/class-wp-html-processor.php:147
Core class used to safely parse and modify an HTML document.

Description

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 HTML Processor supports all elements other than a specific set:

  • Any element inside a TABLE.
  • Any element inside foreign content, including SVG and MATH.
  • Any element outside the IN BODY insertion mode, e.g. doctype declarations, meta, links.

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 illustrates some common examples of unexpected HTML inputs that the HTML Processor properly parses and represents:

  • HTML with optional tags omitted, e.g. <p>one<p>two.
  • HTML with unexpected tag closers, e.g. <p>one </span> more</p>.
  • Non-void tags with self-closing flag, e.g. <div/>the DIV is still open.</div>.
  • Heading elements which close open heading elements of another level, e.g. <h1>Closed by </h2>.
  • Elements containing text that looks like other tags but isn't, e.g. <title>The <img> is plaintext</title>.
  • SCRIPT and STYLE tags containing text that looks like HTML but isn't, e.g. <script>document.write('<p>Hi</p>');</script>.
  • SCRIPT content which has been escaped, e.g. <script><!-- document.write('<script>console.log("hi")</script>') --></script>.

Unsupported Features

This parser does not report parse errors.

Normally, when additional HTML or BODY tags are encountered in a document, if there are any additional attributes on them that aren't found on the previous elements, the existing HTML and BODY elements adopt those missing attribute values. This parser does not add those additional attributes.

In certain situations, elements are moved to a different part of the document in a process called "adoption" and "fostering." Because the nodes move to a location in the document that the parser had already processed, this parser does not support these situations and will bail.

The parser does not implement the "maybe clone an option into selectedcontent" algorithm.
SELECTEDCONTENT elements may not reflect the actual selected content.

Compatibility

WordPress
since 6.4.0
  • 6.7.7
  • 6.8.8
  • 6.9.7
  • 7.0.4
  • 7.1.0

Present in every tracked release (6.7.7 to 7.1.0).

Properties · 9

$stateWP_HTML_Processor_Stateprivate
Holds the working state of the parser, including the stack of open elements and the stack of active formatting elements.
$bookmark_counterintprivate
Used to create unique bookmark names.
$last_errorstring|nullprivate
Stores an explanation for why something failed, if it did.
$unsupported_exceptionWP_HTML_Unsupported_Exception|nullprivate
Stores context for why the parser bailed on unsupported HTML, if it did.
$release_internal_bookmark_on_destructClosure|nullprivate
Releases a bookmark when PHP garbage-collects its wrapping WP_HTML_Token instance.
$element_queueWP_HTML_Stack_Event[]private
Stores stack events which arise during parsing of the HTML document, which will then supply the "match" events.
$breadcrumbsstring[]private
Stores the current breadcrumbs.
$current_elementWP_HTML_Stack_Event|nullprivate
Current stack event, if set, representing a matched token.
$context_nodeWP_HTML_Token|nullprivate
Context node if created as a fragment parser.

Methods · 79

Source code

View on Trac View on GitHub 

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	 * @since 7.0.0 Increased from 100 to 10,000	 *	 * @var int	 */	const MAX_BOOKMARKS = 10_000; 	/**	 * 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; 	/**	 * 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; 	/**	 * 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.	 *	 * 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|null	 */	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.

Changelog

Introduced in 6.4.0. 5 changes between 6.7.7 and 7.1.0.

  1. 6.7.7
  2. 6.8.8
  3. 6.9.7
  4. 7.0.4
  5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

7.1.0
Method escape_text_for_serialization() added.verified against source
7.1.0
Method in_body_any_other_end_tag() added.verified against source
7.1.0
Method step_in_select() removed.verified against source
7.1.0
Method step_in_select_in_table() removed.verified against source
6.8.8
Method create_fragment_at_current_node() added.verified against source
6.4.0
Introduced.from the docblock

About this page

Parsed data
Generated from the wordpress-develop 7.1.0 tag, from src/wp-includes/html-api/class-wp-html-processor.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.
Corrections
Something wrong on this page? Report it and it gets fixed in the next regeneration.