Class: WP_HTML_Tag_Processor  - X-Ref

Core class used to modify attributes in an HTML document for tags matching a query.

## Usage

Use of this class requires three steps:

1. Create a new class instance with your input HTML document.
2. Find the tag(s) you are looking for.
3. Request changes to the attributes in those tag(s).

Example:

$tags = new WP_HTML_Tag_Processor( $html );
if ( $tags->next_tag( 'option' ) ) {
$tags->set_attribute( 'selected', true );
}

### Finding tags

The `next_tag()` function moves the internal cursor through
your input HTML document until it finds a tag meeting any of
the supplied restrictions in the optional query argument. If
no argument is provided then it will find the next HTML tag,
regardless of what kind it is.

If you want to _find whatever the next tag is_:

$tags->next_tag();

| Goal                                                      | Query                                                                           |
|-----------------------------------------------------------|---------------------------------------------------------------------------------|
| Find any tag.                                             | `$tags->next_tag();`                                                            |
| Find next image tag.                                      | `$tags->next_tag( array( 'tag_name' => 'img' ) );`                              |
| Find next image tag (without passing the array).          | `$tags->next_tag( 'img' );`                                                     |
| Find next tag containing the `fullwidth` CSS class.       | `$tags->next_tag( array( 'class_name' => 'fullwidth' ) );`                      |
| Find next image tag containing the `fullwidth` CSS class. | `$tags->next_tag( array( 'tag_name' => 'img', 'class_name' => 'fullwidth' ) );` |

If a tag was found meeting your criteria then `next_tag()`
will return `true` and you can proceed to modify it. If it
returns `false`, however, it failed to find the tag and
moved the cursor to the end of the file.

Once the cursor reaches the end of the file the processor
is done and if you want to reach an earlier tag you will
need to recreate the processor and start over, as it's
unable to back up or move in reverse.

See the section on bookmarks for an exception to this
no-backing-up rule.

#### Custom queries

Sometimes it's necessary to further inspect an HTML tag than
the query syntax here permits. In these cases one may further
inspect the search results using the read-only functions
provided by the processor or external state or variables.

Example:

// Paint up to the first five DIV or SPAN tags marked with the "jazzy" style.
$remaining_count = 5;
while ( $remaining_count > 0 && $tags->next_tag() ) {
if (
( 'DIV' === $tags->get_tag() || 'SPAN' === $tags->get_tag() ) &&
'jazzy' === $tags->get_attribute( 'data-style' )
) {
$tags->add_class( 'theme-style-everest-jazz' );
$remaining_count--;
}
}

`get_attribute()` will return `null` if the attribute wasn't present
on the tag when it was called. It may return `""` (the empty string)
in cases where the attribute was present but its value was empty.
For boolean attributes, those whose name is present but no value is
given, it will return `true` (the only way to set `false` for an
attribute is to remove it).

#### When matching fails

When `next_tag()` returns `false` it could mean different things:

- The requested tag wasn't found in the input document.
- The input document ended in the middle of an HTML syntax element.

When a document ends in the middle of a syntax element it will pause
the processor. This is to make it possible in the future to extend the
input document and proceed - an important requirement for chunked
streaming parsing of a document.

Example:

$processor = new WP_HTML_Tag_Processor( 'This <div is="a" partial="token' );
false === $processor->next_tag();

If a special element (see next section) is encountered but no closing tag
is found it will count as an incomplete tag. The parser will pause as if
the opening tag were incomplete.

Example:

$processor = new WP_HTML_Tag_Processor( '<style>// there could be more styling to come' );
false === $processor->next_tag();

$processor = new WP_HTML_Tag_Processor( '<style>// this is everything</style><div>' );
true === $processor->next_tag( 'DIV' );

#### Special self-contained elements

Some HTML elements are handled in a special way; their start and end tags
act like a void tag. These are special because their contents can't contain
HTML markup. Everything inside these elements is handled in a special way
and content that _appears_ like HTML tags inside of them isn't. There can
be no nesting in these elements.

In the following list, "raw text" means that all of the content in the HTML
until the matching closing tag is treated verbatim without any replacements
and without any parsing.

- IFRAME allows no content but requires a closing tag.
- NOEMBED (deprecated) content is raw text.
- NOFRAMES (deprecated) content is raw text.
- SCRIPT content is plaintext apart from legacy rules allowing `</script>` inside an HTML comment.
- STYLE content is raw text.
- TITLE content is plain text but character references are decoded.
- TEXTAREA content is plain text but character references are decoded.
- XMP (deprecated) content is raw text.

### Modifying HTML attributes for a found tag

Once you've found the start of an opening tag you can modify
any number of the attributes on that tag. You can set a new
value for an attribute, remove the entire attribute, or do
nothing and move on to the next opening tag.

Example:

if ( $tags->next_tag( array( 'class_name' => 'wp-group-block' ) ) ) {
$tags->set_attribute( 'title', 'This groups the contained content.' );
$tags->remove_attribute( 'data-test-id' );
}

If `set_attribute()` is called for an existing attribute it will
overwrite the existing value. Similarly, calling `remove_attribute()`
for a non-existing attribute has no effect on the document. Both
of these methods are safe to call without knowing if a given attribute
exists beforehand.

### Modifying CSS classes for a found tag

The tag processor treats the `class` attribute as a special case.
Because it's a common operation to add or remove CSS classes, this
interface adds helper methods to make that easier.

As with attribute values, adding or removing CSS classes is a safe
operation that doesn't require checking if the attribute or class
exists before making changes. If removing the only class then the
entire `class` attribute will be removed.

Example:

// from `<span>Yippee!</span>`
//   to `<span class="is-active">Yippee!</span>`
$tags->add_class( 'is-active' );

// from `<span class="excited">Yippee!</span>`
//   to `<span class="excited is-active">Yippee!</span>`
$tags->add_class( 'is-active' );

// from `<span class="is-active heavy-accent">Yippee!</span>`
//   to `<span class="is-active heavy-accent">Yippee!</span>`
$tags->add_class( 'is-active' );

// from `<input type="text" class="is-active rugby not-disabled" length="24">`
//   to `<input type="text" class="is-active not-disabled" length="24">
$tags->remove_class( 'rugby' );

// from `<input type="text" class="rugby" length="24">`
//   to `<input type="text" length="24">
$tags->remove_class( 'rugby' );

// from `<input type="text" length="24">`
//   to `<input type="text" length="24">
$tags->remove_class( 'rugby' );

When class changes are enqueued but a direct change to `class` is made via
`set_attribute` then the changes to `set_attribute` (or `remove_attribute`)
will take precedence over those made through `add_class` and `remove_class`.

### Bookmarks

While scanning through the input HTMl document it's possible to set
a named bookmark when a particular tag is found. Later on, after
continuing to scan other tags, it's possible to `seek` to one of
the set bookmarks and then proceed again from that point forward.

Because bookmarks create processing overhead one should avoid
creating too many of them. As a rule, create only bookmarks
of known string literal names; avoid creating "mark_{$index}"
and so on. It's fine from a performance standpoint to create a
bookmark and update it frequently, such as within a loop.

$total_todos = 0;
while ( $p->next_tag( array( 'tag_name' => 'UL', 'class_name' => 'todo' ) ) ) {
$p->set_bookmark( 'list-start' );
while ( $p->next_tag( array( 'tag_closers' => 'visit' ) ) ) {
if ( 'UL' === $p->get_tag() && $p->is_tag_closer() ) {
$p->set_bookmark( 'list-end' );
$p->seek( 'list-start' );
$p->set_attribute( 'data-contained-todos', (string) $total_todos );
$total_todos = 0;
$p->seek( 'list-end' );
break;
}

if ( 'LI' === $p->get_tag() && ! $p->is_tag_closer() ) {
$total_todos++;
}
}
}

## Tokens and finer-grained processing.

It's possible to scan through every lexical token in the
HTML document using the `next_token()` function. This
alternative form takes no argument and provides no built-in
query syntax.

Example:

$title = '(untitled)';
$text  = '';
while ( $processor->next_token() ) {
switch ( $processor->get_token_name() ) {
case '#text':
$text .= $processor->get_modifiable_text();
break;

case 'BR':
$text .= "\n";
break;

case 'TITLE':
$title = $processor->get_modifiable_text();
break;
}
}
return trim( "# {$title}\n\n{$text}" );

### Tokens and _modifiable text_.

#### Special "atomic" HTML elements.

Not all HTML elements are able to contain other elements inside of them.
For instance, the contents inside a TITLE element are plaintext (except
that character references like &amp; will be decoded). This means that
if the string `<img>` appears inside a TITLE element, then it's not an
image tag, but rather it's text describing an image tag. Likewise, the
contents of a SCRIPT or STYLE element are handled entirely separately in
a browser than the contents of other elements because they represent a
different language than HTML.

For these elements the Tag Processor treats the entire sequence as one,
from the opening tag, including its contents, through its closing tag.
This means that the it's not possible to match the closing tag for a
SCRIPT element unless it's unexpected; the Tag Processor already matched
it when it found the opening tag.

The inner contents of these elements are that element's _modifiable text_.

The special elements are:
- `SCRIPT` whose contents are treated as raw plaintext but supports a legacy
style of including JavaScript inside of HTML comments to avoid accidentally
closing the SCRIPT from inside a JavaScript string. E.g. `console.log( '</script>' )`.
- `TITLE` and `TEXTAREA` whose contents are treated as plaintext and then any
character references are decoded. E.g. `1 &lt; 2 < 3` becomes `1 < 2 < 3`.
- `IFRAME`, `NOSCRIPT`, `NOEMBED`, `NOFRAME`, `STYLE` whose contents are treated as
raw plaintext and left as-is. E.g. `1 &lt; 2 < 3` remains `1 &lt; 2 < 3`.

#### Other tokens with modifiable text.

There are also non-elements which are void/self-closing in nature and contain
modifiable text that is part of that individual syntax token itself.

- `#text` nodes, whose entire token _is_ the modifiable text.
- HTML comments and tokens that become comments due to some syntax error. The
text for these tokens is the portion of the comment inside of the syntax.
E.g. for `<!-- comment -->` the text is `" comment "` (note the spaces are included).
- `CDATA` sections, whose text is the content inside of the section itself. E.g. for
`<![CDATA[some content]]>` the text is `"some content"` (with restrictions [1]).
- "Funky comments," which are a special case of invalid closing tags whose name is
invalid. The text for these nodes is the text that a browser would transform into
an HTML comment when parsing. E.g. for `</%post_author>` the text is `%post_author`.
- `DOCTYPE` declarations like `<DOCTYPE html>` which have no closing tag.
- XML Processing instruction nodes like `<?wp __( "Like" ); ?>` (with restrictions [2]).
- The empty end tag `</>` which is ignored in the browser and DOM.

[1]: There are no CDATA sections in HTML. When encountering `<![CDATA[`, everything
until the next `>` becomes a bogus HTML comment, meaning there can be no CDATA
section in an HTML document containing `>`. The Tag Processor will first find
all valid and bogus HTML comments, and then if the comment _would_ have been a
CDATA section _were they to exist_, it will indicate this as the type of comment.

[2]: XML allows a broader range of characters in a processing instruction's target name
and disallows "xml" as a name, since it's special. The Tag Processor only recognizes
target names with an ASCII-representable subset of characters. It also exhibits the
same constraint as with CDATA sections, in that `>` cannot exist within the token
since Processing Instructions do no exist within HTML and their syntax transforms
into a bogus comment in the DOM.

## Design and limitations

The Tag Processor is designed to linearly scan HTML documents and tokenize
HTML tags and their attributes. It's designed to do this as efficiently as
possible without compromising parsing integrity. Therefore it will be
slower than some methods of modifying HTML, such as those incorporating
over-simplified PCRE patterns, but will not introduce the defects and
failures that those methods bring in, which lead to broken page renders
and often to security vulnerabilities. On the other hand, it will be faster
than full-blown HTML parsers such as DOMDocument and use considerably
less memory. It requires a negligible memory overhead, enough to consider
it a zero-overhead system.

The performance characteristics are maintained by avoiding tree construction
and semantic cleanups which are specified in HTML5. Because of this, for
example, it's not possible for the Tag Processor to associate any given
opening tag with its corresponding closing tag, or to return the inner markup
inside an element. Systems may be built on top of the Tag Processor to do
this, but the Tag Processor is and should be constrained so it can remain an
efficient, low-level, and reliable HTML scanner.

The Tag Processor's design incorporates a "garbage-in-garbage-out" philosophy.
HTML5 specifies that certain invalid content be transformed into different forms
for display, such as removing null bytes from an input document and replacing
invalid characters with the Unicode replacement character `U+FFFD` (visually "�").
Where errors or transformations exist within the HTML5 specification, the Tag Processor
leaves those invalid inputs untouched, passing them through to the final browser
to handle. While this implies that certain operations will be non-spec-compliant,
such as reading the value of an attribute with invalid content, it also preserves a
simplicity and efficiency for handling those error cases.

Most operations within the Tag Processor are designed to minimize the difference
between an input and output document for any given change. For example, the
`add_class` and `remove_class` methods preserve whitespace and the class ordering
within the `class` attribute; and when encountering tags with duplicated attributes,
the Tag Processor will leave those invalid duplicate attributes where they are but
update the proper attribute which the browser will read for parsing its value. An
exception to this rule is that all attribute updates store their values as
double-quoted strings, meaning that attributes on input with single-quoted or
unquoted values will appear in the output with double-quotes.

### Scripting Flag

The Tag Processor parses HTML with the "scripting flag" disabled. This means
that it doesn't run any scripts while parsing the page. In a browser with
JavaScript enabled, for example, the script can change the parse of the
document as it loads. On the server, however, evaluating JavaScript is not
only impractical, but also unwanted.

Practically this means that the Tag Processor will descend into NOSCRIPT
elements and process its child tags. Were the scripting flag enabled, such
as in a typical browser, the contents of NOSCRIPT are skipped entirely.

This allows the HTML API to process the content that will be presented in
a browser when scripting is disabled, but it offers a different view of a
page than most browser sessions will experience. E.g. the tags inside the
NOSCRIPT disappear.

### Text Encoding

The Tag Processor assumes that the input HTML document is encoded with a
text encoding compatible with 7-bit ASCII's '<', '>', '&', ';', '/', '=',
"'", '"', 'a' - 'z', 'A' - 'Z', and the whitespace characters ' ', tab,
carriage-return, newline, and form-feed.

In practice, this includes almost every single-byte encoding as well as
UTF-8. Notably, however, it does not include UTF-16. If providing input
that's incompatible, then convert the encoding beforehand.