Class: WP_HTML_Processor  - X-Ref

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