mirror of
https://github.com/WordPress/WordPress.git
synced 2024-08-25 15:22:53 +02:00
When `next_token()` was introduced to the HTML Tag Processor, it started classifying comments that look like they were intended to be CDATA sections. In one of the changes made during development, however, a typo slipped through code review that treated comments as CDATA even if they only ended in `]>` and not the required `]]>`. The consequences of this defect were minor because in all cases these are treated as HTML comments from invalid syntax, but this patch adds the missing check to ensure the proper reporting of CDATA-lookalikes. Follow-up to [57348] Props jonsurrell Fixes #60406 Built from https://develop.svn.wordpress.org/trunk@57506 git-svn-id: http://core.svn.wordpress.org/trunk@57007 1a063a9b-81f0-0310-95a4-ce76da25c4cd
3496 lines
113 KiB
PHP
3496 lines
113 KiB
PHP
<?php
|
||
/**
|
||
* HTML API: WP_HTML_Tag_Processor class
|
||
*
|
||
* Scans through an HTML document to find specific tags, then
|
||
* transforms those tags by adding, removing, or updating the
|
||
* values of the HTML attributes within that tag (opener).
|
||
*
|
||
* Does not fully parse HTML or _recurse_ into the HTML structure
|
||
* Instead this scans linearly through a document and only parses
|
||
* the HTML tag openers.
|
||
*
|
||
* ### Possible future direction for this module
|
||
*
|
||
* - Prune the whitespace when removing classes/attributes: e.g. "a b c" -> "c" not " c".
|
||
* This would increase the size of the changes for some operations but leave more
|
||
* natural-looking output HTML.
|
||
* - Properly decode HTML character references in `get_attribute()`. PHP's
|
||
* `html_entity_decode()` is wrong in a couple ways: it doesn't account for the
|
||
* no-ambiguous-ampersand rule, and it improperly handles the way semicolons may
|
||
* or may not terminate a character reference.
|
||
*
|
||
* @package WordPress
|
||
* @subpackage HTML-API
|
||
* @since 6.2.0
|
||
*/
|
||
|
||
/**
|
||
* 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 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 & 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 < 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 < 2 < 3` remains `1 < 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 "<22>").
|
||
* 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.
|
||
*
|
||
* @since 6.2.0
|
||
* @since 6.2.1 Fix: Support for various invalid comments; attribute updates are case-insensitive.
|
||
* @since 6.3.2 Fix: Skip HTML-like content inside rawtext elements such as STYLE.
|
||
* @since 6.5.0 Pauses processor when input ends in an incomplete syntax token.
|
||
* Introduces "special" elements which act like void elements, e.g. TITLE, STYLE.
|
||
* Allows scanning through all tokens and processing modifiable text, where applicable.
|
||
*/
|
||
class WP_HTML_Tag_Processor {
|
||
/**
|
||
* The maximum number of bookmarks allowed to exist at
|
||
* any given time.
|
||
*
|
||
* @since 6.2.0
|
||
* @var int
|
||
*
|
||
* @see WP_HTML_Tag_Processor::set_bookmark()
|
||
*/
|
||
const MAX_BOOKMARKS = 10;
|
||
|
||
/**
|
||
* Maximum number of times seek() can be called.
|
||
* Prevents accidental infinite loops.
|
||
*
|
||
* @since 6.2.0
|
||
* @var int
|
||
*
|
||
* @see WP_HTML_Tag_Processor::seek()
|
||
*/
|
||
const MAX_SEEK_OPS = 1000;
|
||
|
||
/**
|
||
* The HTML document to parse.
|
||
*
|
||
* @since 6.2.0
|
||
* @var string
|
||
*/
|
||
protected $html;
|
||
|
||
/**
|
||
* The last query passed to next_tag().
|
||
*
|
||
* @since 6.2.0
|
||
* @var array|null
|
||
*/
|
||
private $last_query;
|
||
|
||
/**
|
||
* The tag name this processor currently scans for.
|
||
*
|
||
* @since 6.2.0
|
||
* @var string|null
|
||
*/
|
||
private $sought_tag_name;
|
||
|
||
/**
|
||
* The CSS class name this processor currently scans for.
|
||
*
|
||
* @since 6.2.0
|
||
* @var string|null
|
||
*/
|
||
private $sought_class_name;
|
||
|
||
/**
|
||
* The match offset this processor currently scans for.
|
||
*
|
||
* @since 6.2.0
|
||
* @var int|null
|
||
*/
|
||
private $sought_match_offset;
|
||
|
||
/**
|
||
* Whether to visit tag closers, e.g. </div>, when walking an input document.
|
||
*
|
||
* @since 6.2.0
|
||
* @var bool
|
||
*/
|
||
private $stop_on_tag_closers;
|
||
|
||
/**
|
||
* Specifies mode of operation of the parser at any given time.
|
||
*
|
||
* | State | Meaning |
|
||
* | ----------------|----------------------------------------------------------------------|
|
||
* | *Ready* | The parser is ready to run. |
|
||
* | *Complete* | There is nothing left to parse. |
|
||
* | *Incomplete* | The HTML ended in the middle of a token; nothing more can be parsed. |
|
||
* | *Matched tag* | Found an HTML tag; it's possible to modify its attributes. |
|
||
* | *Text node* | Found a #text node; this is plaintext and modifiable. |
|
||
* | *CDATA node* | Found a CDATA section; this is modifiable. |
|
||
* | *Comment* | Found a comment or bogus comment; this is modifiable. |
|
||
* | *Presumptuous* | Found an empty tag closer: `</>`. |
|
||
* | *Funky comment* | Found a tag closer with an invalid tag name; this is modifiable. |
|
||
*
|
||
* @since 6.5.0
|
||
*
|
||
* @see WP_HTML_Tag_Processor::STATE_READY
|
||
* @see WP_HTML_Tag_Processor::STATE_COMPLETE
|
||
* @see WP_HTML_Tag_Processor::STATE_INCOMPLETE_INPUT
|
||
* @see WP_HTML_Tag_Processor::STATE_MATCHED_TAG
|
||
* @see WP_HTML_Tag_Processor::STATE_TEXT_NODE
|
||
* @see WP_HTML_Tag_Processor::STATE_CDATA_NODE
|
||
* @see WP_HTML_Tag_Processor::STATE_COMMENT
|
||
* @see WP_HTML_Tag_Processor::STATE_DOCTYPE
|
||
* @see WP_HTML_Tag_Processor::STATE_PRESUMPTUOUS_TAG
|
||
* @see WP_HTML_Tag_Processor::STATE_FUNKY_COMMENT
|
||
*
|
||
* @var string
|
||
*/
|
||
protected $parser_state = self::STATE_READY;
|
||
|
||
/**
|
||
* What kind of syntax token became an HTML comment.
|
||
*
|
||
* Since there are many ways in which HTML syntax can create an HTML comment,
|
||
* this indicates which of those caused it. This allows the Tag Processor to
|
||
* represent more from the original input document than would appear in the DOM.
|
||
*
|
||
* @since 6.5.0
|
||
*
|
||
* @var string|null
|
||
*/
|
||
protected $comment_type = null;
|
||
|
||
/**
|
||
* How many bytes from the original HTML document have been read and parsed.
|
||
*
|
||
* This value points to the latest byte offset in the input document which
|
||
* has been already parsed. It is the internal cursor for the Tag Processor
|
||
* and updates while scanning through the HTML tokens.
|
||
*
|
||
* @since 6.2.0
|
||
* @var int
|
||
*/
|
||
private $bytes_already_parsed = 0;
|
||
|
||
/**
|
||
* Byte offset in input document where current token starts.
|
||
*
|
||
* Example:
|
||
*
|
||
* <div id="test">...
|
||
* 01234
|
||
* - token starts at 0
|
||
*
|
||
* @since 6.5.0
|
||
*
|
||
* @var int|null
|
||
*/
|
||
private $token_starts_at;
|
||
|
||
/**
|
||
* Byte length of current token.
|
||
*
|
||
* Example:
|
||
*
|
||
* <div id="test">...
|
||
* 012345678901234
|
||
* - token length is 14 - 0 = 14
|
||
*
|
||
* a <!-- comment --> is a token.
|
||
* 0123456789 123456789 123456789
|
||
* - token length is 17 - 2 = 15
|
||
*
|
||
* @since 6.5.0
|
||
*
|
||
* @var int|null
|
||
*/
|
||
private $token_length;
|
||
|
||
/**
|
||
* Byte offset in input document where current tag name starts.
|
||
*
|
||
* Example:
|
||
*
|
||
* <div id="test">...
|
||
* 01234
|
||
* - tag name starts at 1
|
||
*
|
||
* @since 6.2.0
|
||
*
|
||
* @var int|null
|
||
*/
|
||
private $tag_name_starts_at;
|
||
|
||
/**
|
||
* Byte length of current tag name.
|
||
*
|
||
* Example:
|
||
*
|
||
* <div id="test">...
|
||
* 01234
|
||
* --- tag name length is 3
|
||
*
|
||
* @since 6.2.0
|
||
*
|
||
* @var int|null
|
||
*/
|
||
private $tag_name_length;
|
||
|
||
/**
|
||
* Byte offset into input document where current modifiable text starts.
|
||
*
|
||
* @since 6.5.0
|
||
*
|
||
* @var int
|
||
*/
|
||
private $text_starts_at;
|
||
|
||
/**
|
||
* Byte length of modifiable text.
|
||
*
|
||
* @since 6.5.0
|
||
*
|
||
* @var string
|
||
*/
|
||
private $text_length;
|
||
|
||
/**
|
||
* Whether the current tag is an opening tag, e.g. <div>, or a closing tag, e.g. </div>.
|
||
*
|
||
* @var bool
|
||
*/
|
||
private $is_closing_tag;
|
||
|
||
/**
|
||
* Lazily-built index of attributes found within an HTML tag, keyed by the attribute name.
|
||
*
|
||
* Example:
|
||
*
|
||
* // Supposing the parser is working through this content
|
||
* // and stops after recognizing the `id` attribute.
|
||
* // <div id="test-4" class=outline title="data:text/plain;base64=asdk3nk1j3fo8">
|
||
* // ^ parsing will continue from this point.
|
||
* $this->attributes = array(
|
||
* 'id' => new WP_HTML_Attribute_Token( 'id', 9, 6, 5, 11, false )
|
||
* );
|
||
*
|
||
* // When picking up parsing again, or when asking to find the
|
||
* // `class` attribute we will continue and add to this array.
|
||
* $this->attributes = array(
|
||
* 'id' => new WP_HTML_Attribute_Token( 'id', 9, 6, 5, 11, false ),
|
||
* 'class' => new WP_HTML_Attribute_Token( 'class', 23, 7, 17, 13, false )
|
||
* );
|
||
*
|
||
* // Note that only the `class` attribute value is stored in the index.
|
||
* // That's because it is the only value used by this class at the moment.
|
||
*
|
||
* @since 6.2.0
|
||
* @var WP_HTML_Attribute_Token[]
|
||
*/
|
||
private $attributes = array();
|
||
|
||
/**
|
||
* Tracks spans of duplicate attributes on a given tag, used for removing
|
||
* all copies of an attribute when calling `remove_attribute()`.
|
||
*
|
||
* @since 6.3.2
|
||
*
|
||
* @var (WP_HTML_Span[])[]|null
|
||
*/
|
||
private $duplicate_attributes = null;
|
||
|
||
/**
|
||
* Which class names to add or remove from a tag.
|
||
*
|
||
* These are tracked separately from attribute updates because they are
|
||
* semantically distinct, whereas this interface exists for the common
|
||
* case of adding and removing class names while other attributes are
|
||
* generally modified as with DOM `setAttribute` calls.
|
||
*
|
||
* When modifying an HTML document these will eventually be collapsed
|
||
* into a single `set_attribute( 'class', $changes )` call.
|
||
*
|
||
* Example:
|
||
*
|
||
* // Add the `wp-block-group` class, remove the `wp-group` class.
|
||
* $classname_updates = array(
|
||
* // Indexed by a comparable class name.
|
||
* 'wp-block-group' => WP_HTML_Tag_Processor::ADD_CLASS,
|
||
* 'wp-group' => WP_HTML_Tag_Processor::REMOVE_CLASS
|
||
* );
|
||
*
|
||
* @since 6.2.0
|
||
* @var bool[]
|
||
*/
|
||
private $classname_updates = array();
|
||
|
||
/**
|
||
* Tracks a semantic location in the original HTML which
|
||
* shifts with updates as they are applied to the document.
|
||
*
|
||
* @since 6.2.0
|
||
* @var WP_HTML_Span[]
|
||
*/
|
||
protected $bookmarks = array();
|
||
|
||
const ADD_CLASS = true;
|
||
const REMOVE_CLASS = false;
|
||
const SKIP_CLASS = null;
|
||
|
||
/**
|
||
* Lexical replacements to apply to input HTML document.
|
||
*
|
||
* "Lexical" in this class refers to the part of this class which
|
||
* operates on pure text _as text_ and not as HTML. There's a line
|
||
* between the public interface, with HTML-semantic methods like
|
||
* `set_attribute` and `add_class`, and an internal state that tracks
|
||
* text offsets in the input document.
|
||
*
|
||
* When higher-level HTML methods are called, those have to transform their
|
||
* operations (such as setting an attribute's value) into text diffing
|
||
* operations (such as replacing the sub-string from indices A to B with
|
||
* some given new string). These text-diffing operations are the lexical
|
||
* updates.
|
||
*
|
||
* As new higher-level methods are added they need to collapse their
|
||
* operations into these lower-level lexical updates since that's the
|
||
* Tag Processor's internal language of change. Any code which creates
|
||
* these lexical updates must ensure that they do not cross HTML syntax
|
||
* boundaries, however, so these should never be exposed outside of this
|
||
* class or any classes which intentionally expand its functionality.
|
||
*
|
||
* These are enqueued while editing the document instead of being immediately
|
||
* applied to avoid processing overhead, string allocations, and string
|
||
* copies when applying many updates to a single document.
|
||
*
|
||
* Example:
|
||
*
|
||
* // Replace an attribute stored with a new value, indices
|
||
* // sourced from the lazily-parsed HTML recognizer.
|
||
* $start = $attributes['src']->start;
|
||
* $length = $attributes['src']->length;
|
||
* $modifications[] = new WP_HTML_Text_Replacement( $start, $length, $new_value );
|
||
*
|
||
* // Correspondingly, something like this will appear in this array.
|
||
* $lexical_updates = array(
|
||
* WP_HTML_Text_Replacement( 14, 28, 'https://my-site.my-domain/wp-content/uploads/2014/08/kittens.jpg' )
|
||
* );
|
||
*
|
||
* @since 6.2.0
|
||
* @var WP_HTML_Text_Replacement[]
|
||
*/
|
||
protected $lexical_updates = array();
|
||
|
||
/**
|
||
* Tracks and limits `seek()` calls to prevent accidental infinite loops.
|
||
*
|
||
* @since 6.2.0
|
||
* @var int
|
||
*
|
||
* @see WP_HTML_Tag_Processor::seek()
|
||
*/
|
||
protected $seek_count = 0;
|
||
|
||
/**
|
||
* Constructor.
|
||
*
|
||
* @since 6.2.0
|
||
*
|
||
* @param string $html HTML to process.
|
||
*/
|
||
public function __construct( $html ) {
|
||
$this->html = $html;
|
||
}
|
||
|
||
/**
|
||
* Finds the next tag matching the $query.
|
||
*
|
||
* @since 6.2.0
|
||
* @since 6.5.0 No longer processes incomplete tokens at end of document; pauses the processor at start of token.
|
||
*
|
||
* @param array|string|null $query {
|
||
* Optional. Which tag name to find, having which class, etc. Default is to find any tag.
|
||
*
|
||
* @type string|null $tag_name Which tag to find, or `null` for "any tag."
|
||
* @type int|null $match_offset Find the Nth tag matching all search criteria.
|
||
* 1 for "first" tag, 3 for "third," etc.
|
||
* Defaults to first tag.
|
||
* @type string|null $class_name Tag must contain this whole class name to match.
|
||
* @type string|null $tag_closers "visit" or "skip": whether to stop on tag closers, e.g. </div>.
|
||
* }
|
||
* @return bool Whether a tag was matched.
|
||
*/
|
||
public function next_tag( $query = null ) {
|
||
$this->parse_query( $query );
|
||
$already_found = 0;
|
||
|
||
do {
|
||
if ( false === $this->next_token() ) {
|
||
return false;
|
||
}
|
||
|
||
if ( self::STATE_MATCHED_TAG !== $this->parser_state ) {
|
||
continue;
|
||
}
|
||
|
||
if ( $this->matches() ) {
|
||
++$already_found;
|
||
}
|
||
} while ( $already_found < $this->sought_match_offset );
|
||
|
||
return true;
|
||
}
|
||
|
||
/**
|
||
* Finds the next token in the HTML document.
|
||
*
|
||
* An HTML document can be viewed as a stream of tokens,
|
||
* where tokens are things like HTML tags, HTML comments,
|
||
* text nodes, etc. This method finds the next token in
|
||
* the HTML document and returns whether it found one.
|
||
*
|
||
* If it starts parsing a token and reaches the end of the
|
||
* document then it will seek to the start of the last
|
||
* token and pause, returning `false` to indicate that it
|
||
* failed to find a complete token.
|
||
*
|
||
* Possible token types, based on the HTML specification:
|
||
*
|
||
* - an HTML tag, whether opening, closing, or void.
|
||
* - a text node - the plaintext inside tags.
|
||
* - an HTML comment.
|
||
* - a DOCTYPE declaration.
|
||
* - a processing instruction, e.g. `<?xml version="1.0" ?>`.
|
||
*
|
||
* The Tag Processor currently only supports the tag token.
|
||
*
|
||
* @since 6.5.0
|
||
*
|
||
* @return bool Whether a token was parsed.
|
||
*/
|
||
public function next_token() {
|
||
$was_at = $this->bytes_already_parsed;
|
||
$this->get_updated_html();
|
||
|
||
// Don't proceed if there's nothing more to scan.
|
||
if (
|
||
self::STATE_COMPLETE === $this->parser_state ||
|
||
self::STATE_INCOMPLETE_INPUT === $this->parser_state
|
||
) {
|
||
return false;
|
||
}
|
||
|
||
/*
|
||
* The next step in the parsing loop determines the parsing state;
|
||
* clear it so that state doesn't linger from the previous step.
|
||
*/
|
||
$this->parser_state = self::STATE_READY;
|
||
|
||
if ( $this->bytes_already_parsed >= strlen( $this->html ) ) {
|
||
$this->parser_state = self::STATE_COMPLETE;
|
||
return false;
|
||
}
|
||
|
||
// Find the next tag if it exists.
|
||
if ( false === $this->parse_next_tag() ) {
|
||
if ( self::STATE_INCOMPLETE_INPUT === $this->parser_state ) {
|
||
$this->bytes_already_parsed = $was_at;
|
||
}
|
||
|
||
return false;
|
||
}
|
||
|
||
/*
|
||
* For legacy reasons the rest of this function handles tags and their
|
||
* attributes. If the processor has reached the end of the document
|
||
* or if it matched any other token then it should return here to avoid
|
||
* attempting to process tag-specific syntax.
|
||
*/
|
||
if (
|
||
self::STATE_INCOMPLETE_INPUT !== $this->parser_state &&
|
||
self::STATE_COMPLETE !== $this->parser_state &&
|
||
self::STATE_MATCHED_TAG !== $this->parser_state
|
||
) {
|
||
return true;
|
||
}
|
||
|
||
// Parse all of its attributes.
|
||
while ( $this->parse_next_attribute() ) {
|
||
continue;
|
||
}
|
||
|
||
// Ensure that the tag closes before the end of the document.
|
||
if (
|
||
self::STATE_INCOMPLETE_INPUT === $this->parser_state ||
|
||
$this->bytes_already_parsed >= strlen( $this->html )
|
||
) {
|
||
// Does this appropriately clear state (parsed attributes)?
|
||
$this->parser_state = self::STATE_INCOMPLETE_INPUT;
|
||
$this->bytes_already_parsed = $was_at;
|
||
|
||
return false;
|
||
}
|
||
|
||
$tag_ends_at = strpos( $this->html, '>', $this->bytes_already_parsed );
|
||
if ( false === $tag_ends_at ) {
|
||
$this->parser_state = self::STATE_INCOMPLETE_INPUT;
|
||
$this->bytes_already_parsed = $was_at;
|
||
|
||
return false;
|
||
}
|
||
$this->parser_state = self::STATE_MATCHED_TAG;
|
||
$this->token_length = $tag_ends_at - $this->token_starts_at;
|
||
$this->bytes_already_parsed = $tag_ends_at + 1;
|
||
|
||
/*
|
||
* For non-DATA sections which might contain text that looks like HTML tags but
|
||
* isn't, scan with the appropriate alternative mode. Looking at the first letter
|
||
* of the tag name as a pre-check avoids a string allocation when it's not needed.
|
||
*/
|
||
$t = $this->html[ $this->tag_name_starts_at ];
|
||
if (
|
||
$this->is_closing_tag ||
|
||
! (
|
||
'i' === $t || 'I' === $t ||
|
||
'n' === $t || 'N' === $t ||
|
||
's' === $t || 'S' === $t ||
|
||
't' === $t || 'T' === $t ||
|
||
'x' === $t || 'X' === $t
|
||
)
|
||
) {
|
||
return true;
|
||
}
|
||
|
||
$tag_name = $this->get_tag();
|
||
|
||
/*
|
||
* Preserve the opening tag pointers, as these will be overwritten
|
||
* when finding the closing tag. They will be reset after finding
|
||
* the closing to tag to point to the opening of the special atomic
|
||
* tag sequence.
|
||
*/
|
||
$tag_name_starts_at = $this->tag_name_starts_at;
|
||
$tag_name_length = $this->tag_name_length;
|
||
$tag_ends_at = $this->token_starts_at + $this->token_length;
|
||
$attributes = $this->attributes;
|
||
$duplicate_attributes = $this->duplicate_attributes;
|
||
|
||
// Find the closing tag if necessary.
|
||
$found_closer = false;
|
||
switch ( $tag_name ) {
|
||
case 'SCRIPT':
|
||
$found_closer = $this->skip_script_data();
|
||
break;
|
||
|
||
case 'TEXTAREA':
|
||
case 'TITLE':
|
||
$found_closer = $this->skip_rcdata( $tag_name );
|
||
break;
|
||
|
||
/*
|
||
* In the browser this list would include the NOSCRIPT element,
|
||
* but the Tag Processor is an environment with the scripting
|
||
* flag disabled, meaning that it needs to descend into the
|
||
* NOSCRIPT element to be able to properly process what will be
|
||
* sent to a browser.
|
||
*
|
||
* Note that this rule makes HTML5 syntax incompatible with XML,
|
||
* because the parsing of this token depends on client application.
|
||
* The NOSCRIPT element cannot be represented in the XHTML syntax.
|
||
*/
|
||
case 'IFRAME':
|
||
case 'NOEMBED':
|
||
case 'NOFRAMES':
|
||
case 'STYLE':
|
||
case 'XMP':
|
||
$found_closer = $this->skip_rawtext( $tag_name );
|
||
break;
|
||
|
||
// No other tags should be treated in their entirety here.
|
||
default:
|
||
return true;
|
||
}
|
||
|
||
if ( ! $found_closer ) {
|
||
$this->parser_state = self::STATE_INCOMPLETE_INPUT;
|
||
$this->bytes_already_parsed = $was_at;
|
||
return false;
|
||
}
|
||
|
||
/*
|
||
* The values here look like they reference the opening tag but they reference
|
||
* the closing tag instead. This is why the opening tag values were stored
|
||
* above in a variable. It reads confusingly here, but that's because the
|
||
* functions that skip the contents have moved all the internal cursors past
|
||
* the inner content of the tag.
|
||
*/
|
||
$this->token_starts_at = $was_at;
|
||
$this->token_length = $this->bytes_already_parsed - $this->token_starts_at;
|
||
$this->text_starts_at = $tag_ends_at + 1;
|
||
$this->text_length = $this->tag_name_starts_at - $this->text_starts_at;
|
||
$this->tag_name_starts_at = $tag_name_starts_at;
|
||
$this->tag_name_length = $tag_name_length;
|
||
$this->attributes = $attributes;
|
||
$this->duplicate_attributes = $duplicate_attributes;
|
||
|
||
return true;
|
||
}
|
||
|
||
/**
|
||
* Whether the processor paused because the input HTML document ended
|
||
* in the middle of a syntax element, such as in the middle of a tag.
|
||
*
|
||
* Example:
|
||
*
|
||
* $processor = new WP_HTML_Tag_Processor( '<input type="text" value="Th' );
|
||
* false === $processor->get_next_tag();
|
||
* true === $processor->paused_at_incomplete_token();
|
||
*
|
||
* @since 6.5.0
|
||
*
|
||
* @return bool Whether the parse paused at the start of an incomplete token.
|
||
*/
|
||
public function paused_at_incomplete_token() {
|
||
return self::STATE_INCOMPLETE_INPUT === $this->parser_state;
|
||
}
|
||
|
||
/**
|
||
* Generator for a foreach loop to step through each class name for the matched tag.
|
||
*
|
||
* This generator function is designed to be used inside a "foreach" loop.
|
||
*
|
||
* Example:
|
||
*
|
||
* $p = new WP_HTML_Tag_Processor( "<div class='free <egg<\tlang-en'>" );
|
||
* $p->next_tag();
|
||
* foreach ( $p->class_list() as $class_name ) {
|
||
* echo "{$class_name} ";
|
||
* }
|
||
* // Outputs: "free <egg> lang-en "
|
||
*
|
||
* @since 6.4.0
|
||
*/
|
||
public function class_list() {
|
||
if ( self::STATE_MATCHED_TAG !== $this->parser_state ) {
|
||
return;
|
||
}
|
||
|
||
/** @var string $class contains the string value of the class attribute, with character references decoded. */
|
||
$class = $this->get_attribute( 'class' );
|
||
|
||
if ( ! is_string( $class ) ) {
|
||
return;
|
||
}
|
||
|
||
$seen = array();
|
||
|
||
$at = 0;
|
||
while ( $at < strlen( $class ) ) {
|
||
// Skip past any initial boundary characters.
|
||
$at += strspn( $class, " \t\f\r\n", $at );
|
||
if ( $at >= strlen( $class ) ) {
|
||
return;
|
||
}
|
||
|
||
// Find the byte length until the next boundary.
|
||
$length = strcspn( $class, " \t\f\r\n", $at );
|
||
if ( 0 === $length ) {
|
||
return;
|
||
}
|
||
|
||
/*
|
||
* CSS class names are case-insensitive in the ASCII range.
|
||
*
|
||
* @see https://www.w3.org/TR/CSS2/syndata.html#x1
|
||
*/
|
||
$name = strtolower( substr( $class, $at, $length ) );
|
||
$at += $length;
|
||
|
||
/*
|
||
* It's expected that the number of class names for a given tag is relatively small.
|
||
* Given this, it is probably faster overall to scan an array for a value rather
|
||
* than to use the class name as a key and check if it's a key of $seen.
|
||
*/
|
||
if ( in_array( $name, $seen, true ) ) {
|
||
continue;
|
||
}
|
||
|
||
$seen[] = $name;
|
||
yield $name;
|
||
}
|
||
}
|
||
|
||
|
||
/**
|
||
* Returns if a matched tag contains the given ASCII case-insensitive class name.
|
||
*
|
||
* @since 6.4.0
|
||
*
|
||
* @param string $wanted_class Look for this CSS class name, ASCII case-insensitive.
|
||
* @return bool|null Whether the matched tag contains the given class name, or null if not matched.
|
||
*/
|
||
public function has_class( $wanted_class ) {
|
||
if ( self::STATE_MATCHED_TAG !== $this->parser_state ) {
|
||
return null;
|
||
}
|
||
|
||
$wanted_class = strtolower( $wanted_class );
|
||
|
||
foreach ( $this->class_list() as $class_name ) {
|
||
if ( $class_name === $wanted_class ) {
|
||
return true;
|
||
}
|
||
}
|
||
|
||
return false;
|
||
}
|
||
|
||
|
||
/**
|
||
* Sets a bookmark in the HTML document.
|
||
*
|
||
* Bookmarks represent specific places or tokens in the HTML
|
||
* document, such as a tag opener or closer. When applying
|
||
* edits to a document, such as setting an attribute, the
|
||
* text offsets of that token may shift; the bookmark is
|
||
* kept updated with those shifts and remains stable unless
|
||
* the entire span of text in which the token sits is removed.
|
||
*
|
||
* Release bookmarks when they are no longer needed.
|
||
*
|
||
* Example:
|
||
*
|
||
* <main><h2>Surprising fact you may not know!</h2></main>
|
||
* ^ ^
|
||
* \-|-- this `H2` opener bookmark tracks the token
|
||
*
|
||
* <main class="clickbait"><h2>Surprising fact you may no…
|
||
* ^ ^
|
||
* \-|-- it shifts with edits
|
||
*
|
||
* Bookmarks provide the ability to seek to a previously-scanned
|
||
* place in the HTML document. This avoids the need to re-scan
|
||
* the entire document.
|
||
*
|
||
* Example:
|
||
*
|
||
* <ul><li>One</li><li>Two</li><li>Three</li></ul>
|
||
* ^^^^
|
||
* want to note this last item
|
||
*
|
||
* $p = new WP_HTML_Tag_Processor( $html );
|
||
* $in_list = false;
|
||
* while ( $p->next_tag( array( 'tag_closers' => $in_list ? 'visit' : 'skip' ) ) ) {
|
||
* if ( 'UL' === $p->get_tag() ) {
|
||
* if ( $p->is_tag_closer() ) {
|
||
* $in_list = false;
|
||
* $p->set_bookmark( 'resume' );
|
||
* if ( $p->seek( 'last-li' ) ) {
|
||
* $p->add_class( 'last-li' );
|
||
* }
|
||
* $p->seek( 'resume' );
|
||
* $p->release_bookmark( 'last-li' );
|
||
* $p->release_bookmark( 'resume' );
|
||
* } else {
|
||
* $in_list = true;
|
||
* }
|
||
* }
|
||
*
|
||
* if ( 'LI' === $p->get_tag() ) {
|
||
* $p->set_bookmark( 'last-li' );
|
||
* }
|
||
* }
|
||
*
|
||
* Bookmarks intentionally hide the internal string offsets
|
||
* to which they refer. They are maintained internally as
|
||
* updates are applied to the HTML document and therefore
|
||
* retain their "position" - the location to which they
|
||
* originally pointed. The inability to use bookmarks with
|
||
* functions like `substr` is therefore intentional to guard
|
||
* against accidentally breaking the HTML.
|
||
*
|
||
* Because bookmarks allocate memory and require processing
|
||
* for every applied update, they are limited and require
|
||
* a name. They should not be created with programmatically-made
|
||
* names, such as "li_{$index}" with some loop. As a general
|
||
* rule they should only be created with string-literal names
|
||
* like "start-of-section" or "last-paragraph".
|
||
*
|
||
* Bookmarks are a powerful tool to enable complicated behavior.
|
||
* Consider double-checking that you need this tool if you are
|
||
* reaching for it, as inappropriate use could lead to broken
|
||
* HTML structure or unwanted processing overhead.
|
||
*
|
||
* @since 6.2.0
|
||
*
|
||
* @param string $name Identifies this particular bookmark.
|
||
* @return bool Whether the bookmark was successfully created.
|
||
*/
|
||
public function set_bookmark( $name ) {
|
||
// It only makes sense to set a bookmark if the parser has paused on a concrete token.
|
||
if (
|
||
self::STATE_COMPLETE === $this->parser_state ||
|
||
self::STATE_INCOMPLETE_INPUT === $this->parser_state
|
||
) {
|
||
return false;
|
||
}
|
||
|
||
if ( ! array_key_exists( $name, $this->bookmarks ) && count( $this->bookmarks ) >= static::MAX_BOOKMARKS ) {
|
||
_doing_it_wrong(
|
||
__METHOD__,
|
||
__( 'Too many bookmarks: cannot create any more.' ),
|
||
'6.2.0'
|
||
);
|
||
return false;
|
||
}
|
||
|
||
$this->bookmarks[ $name ] = new WP_HTML_Span( $this->token_starts_at, $this->token_length );
|
||
|
||
return true;
|
||
}
|
||
|
||
|
||
/**
|
||
* Removes a bookmark that is no longer needed.
|
||
*
|
||
* Releasing a bookmark frees up the small
|
||
* performance overhead it requires.
|
||
*
|
||
* @param string $name Name of the bookmark to remove.
|
||
* @return bool Whether the bookmark already existed before removal.
|
||
*/
|
||
public function release_bookmark( $name ) {
|
||
if ( ! array_key_exists( $name, $this->bookmarks ) ) {
|
||
return false;
|
||
}
|
||
|
||
unset( $this->bookmarks[ $name ] );
|
||
|
||
return true;
|
||
}
|
||
|
||
/**
|
||
* Skips contents of generic rawtext elements.
|
||
*
|
||
* @since 6.3.2
|
||
*
|
||
* @see https://html.spec.whatwg.org/#generic-raw-text-element-parsing-algorithm
|
||
*
|
||
* @param string $tag_name The uppercase tag name which will close the RAWTEXT region.
|
||
* @return bool Whether an end to the RAWTEXT region was found before the end of the document.
|
||
*/
|
||
private function skip_rawtext( $tag_name ) {
|
||
/*
|
||
* These two functions distinguish themselves on whether character references are
|
||
* decoded, and since functionality to read the inner markup isn't supported, it's
|
||
* not necessary to implement these two functions separately.
|
||
*/
|
||
return $this->skip_rcdata( $tag_name );
|
||
}
|
||
|
||
/**
|
||
* Skips contents of RCDATA elements, namely title and textarea tags.
|
||
*
|
||
* @since 6.2.0
|
||
*
|
||
* @see https://html.spec.whatwg.org/multipage/parsing.html#rcdata-state
|
||
*
|
||
* @param string $tag_name The uppercase tag name which will close the RCDATA region.
|
||
* @return bool Whether an end to the RCDATA region was found before the end of the document.
|
||
*/
|
||
private function skip_rcdata( $tag_name ) {
|
||
$html = $this->html;
|
||
$doc_length = strlen( $html );
|
||
$tag_length = strlen( $tag_name );
|
||
|
||
$at = $this->bytes_already_parsed;
|
||
|
||
while ( false !== $at && $at < $doc_length ) {
|
||
$at = strpos( $this->html, '</', $at );
|
||
$this->tag_name_starts_at = $at;
|
||
|
||
// Fail if there is no possible tag closer.
|
||
if ( false === $at || ( $at + $tag_length ) >= $doc_length ) {
|
||
return false;
|
||
}
|
||
|
||
$at += 2;
|
||
|
||
/*
|
||
* Find a case-insensitive match to the tag name.
|
||
*
|
||
* Because tag names are limited to US-ASCII there is no
|
||
* need to perform any kind of Unicode normalization when
|
||
* comparing; any character which could be impacted by such
|
||
* normalization could not be part of a tag name.
|
||
*/
|
||
for ( $i = 0; $i < $tag_length; $i++ ) {
|
||
$tag_char = $tag_name[ $i ];
|
||
$html_char = $html[ $at + $i ];
|
||
|
||
if ( $html_char !== $tag_char && strtoupper( $html_char ) !== $tag_char ) {
|
||
$at += $i;
|
||
continue 2;
|
||
}
|
||
}
|
||
|
||
$at += $tag_length;
|
||
$this->bytes_already_parsed = $at;
|
||
|
||
if ( $at >= strlen( $html ) ) {
|
||
return false;
|
||
}
|
||
|
||
/*
|
||
* Ensure that the tag name terminates to avoid matching on
|
||
* substrings of a longer tag name. For example, the sequence
|
||
* "</textarearug" should not match for "</textarea" even
|
||
* though "textarea" is found within the text.
|
||
*/
|
||
$c = $html[ $at ];
|
||
if ( ' ' !== $c && "\t" !== $c && "\r" !== $c && "\n" !== $c && '/' !== $c && '>' !== $c ) {
|
||
continue;
|
||
}
|
||
|
||
while ( $this->parse_next_attribute() ) {
|
||
continue;
|
||
}
|
||
|
||
$at = $this->bytes_already_parsed;
|
||
if ( $at >= strlen( $this->html ) ) {
|
||
return false;
|
||
}
|
||
|
||
if ( '>' === $html[ $at ] ) {
|
||
$this->bytes_already_parsed = $at + 1;
|
||
return true;
|
||
}
|
||
|
||
if ( $at + 1 >= strlen( $this->html ) ) {
|
||
return false;
|
||
}
|
||
|
||
if ( '/' === $html[ $at ] && '>' === $html[ $at + 1 ] ) {
|
||
$this->bytes_already_parsed = $at + 2;
|
||
return true;
|
||
}
|
||
}
|
||
|
||
return false;
|
||
}
|
||
|
||
/**
|
||
* Skips contents of script tags.
|
||
*
|
||
* @since 6.2.0
|
||
*
|
||
* @return bool Whether the script tag was closed before the end of the document.
|
||
*/
|
||
private function skip_script_data() {
|
||
$state = 'unescaped';
|
||
$html = $this->html;
|
||
$doc_length = strlen( $html );
|
||
$at = $this->bytes_already_parsed;
|
||
|
||
while ( false !== $at && $at < $doc_length ) {
|
||
$at += strcspn( $html, '-<', $at );
|
||
|
||
/*
|
||
* For all script states a "-->" transitions
|
||
* back into the normal unescaped script mode,
|
||
* even if that's the current state.
|
||
*/
|
||
if (
|
||
$at + 2 < $doc_length &&
|
||
'-' === $html[ $at ] &&
|
||
'-' === $html[ $at + 1 ] &&
|
||
'>' === $html[ $at + 2 ]
|
||
) {
|
||
$at += 3;
|
||
$state = 'unescaped';
|
||
continue;
|
||
}
|
||
|
||
// Everything of interest past here starts with "<".
|
||
if ( $at + 1 >= $doc_length || '<' !== $html[ $at++ ] ) {
|
||
continue;
|
||
}
|
||
|
||
/*
|
||
* Unlike with "-->", the "<!--" only transitions
|
||
* into the escaped mode if not already there.
|
||
*
|
||
* Inside the escaped modes it will be ignored; and
|
||
* should never break out of the double-escaped
|
||
* mode and back into the escaped mode.
|
||
*
|
||
* While this requires a mode change, it does not
|
||
* impact the parsing otherwise, so continue
|
||
* parsing after updating the state.
|
||
*/
|
||
if (
|
||
$at + 2 < $doc_length &&
|
||
'!' === $html[ $at ] &&
|
||
'-' === $html[ $at + 1 ] &&
|
||
'-' === $html[ $at + 2 ]
|
||
) {
|
||
$at += 3;
|
||
$state = 'unescaped' === $state ? 'escaped' : $state;
|
||
continue;
|
||
}
|
||
|
||
if ( '/' === $html[ $at ] ) {
|
||
$closer_potentially_starts_at = $at - 1;
|
||
$is_closing = true;
|
||
++$at;
|
||
} else {
|
||
$is_closing = false;
|
||
}
|
||
|
||
/*
|
||
* At this point the only remaining state-changes occur with the
|
||
* <script> and </script> tags; unless one of these appears next,
|
||
* proceed scanning to the next potential token in the text.
|
||
*/
|
||
if ( ! (
|
||
$at + 6 < $doc_length &&
|
||
( 's' === $html[ $at ] || 'S' === $html[ $at ] ) &&
|
||
( 'c' === $html[ $at + 1 ] || 'C' === $html[ $at + 1 ] ) &&
|
||
( 'r' === $html[ $at + 2 ] || 'R' === $html[ $at + 2 ] ) &&
|
||
( 'i' === $html[ $at + 3 ] || 'I' === $html[ $at + 3 ] ) &&
|
||
( 'p' === $html[ $at + 4 ] || 'P' === $html[ $at + 4 ] ) &&
|
||
( 't' === $html[ $at + 5 ] || 'T' === $html[ $at + 5 ] )
|
||
) ) {
|
||
++$at;
|
||
continue;
|
||
}
|
||
|
||
/*
|
||
* Ensure that the script tag terminates to avoid matching on
|
||
* substrings of a non-match. For example, the sequence
|
||
* "<script123" should not end a script region even though
|
||
* "<script" is found within the text.
|
||
*/
|
||
if ( $at + 6 >= $doc_length ) {
|
||
continue;
|
||
}
|
||
$at += 6;
|
||
$c = $html[ $at ];
|
||
if ( ' ' !== $c && "\t" !== $c && "\r" !== $c && "\n" !== $c && '/' !== $c && '>' !== $c ) {
|
||
++$at;
|
||
continue;
|
||
}
|
||
|
||
if ( 'escaped' === $state && ! $is_closing ) {
|
||
$state = 'double-escaped';
|
||
continue;
|
||
}
|
||
|
||
if ( 'double-escaped' === $state && $is_closing ) {
|
||
$state = 'escaped';
|
||
continue;
|
||
}
|
||
|
||
if ( $is_closing ) {
|
||
$this->bytes_already_parsed = $closer_potentially_starts_at;
|
||
$this->tag_name_starts_at = $closer_potentially_starts_at;
|
||
if ( $this->bytes_already_parsed >= $doc_length ) {
|
||
return false;
|
||
}
|
||
|
||
while ( $this->parse_next_attribute() ) {
|
||
continue;
|
||
}
|
||
|
||
if ( $this->bytes_already_parsed >= $doc_length ) {
|
||
$this->parser_state = self::STATE_INCOMPLETE_INPUT;
|
||
|
||
return false;
|
||
}
|
||
|
||
if ( '>' === $html[ $this->bytes_already_parsed ] ) {
|
||
++$this->bytes_already_parsed;
|
||
return true;
|
||
}
|
||
}
|
||
|
||
++$at;
|
||
}
|
||
|
||
return false;
|
||
}
|
||
|
||
/**
|
||
* Parses the next tag.
|
||
*
|
||
* This will find and start parsing the next tag, including
|
||
* the opening `<`, the potential closer `/`, and the tag
|
||
* name. It does not parse the attributes or scan to the
|
||
* closing `>`; these are left for other methods.
|
||
*
|
||
* @since 6.2.0
|
||
* @since 6.2.1 Support abruptly-closed comments, invalid-tag-closer-comments, and empty elements.
|
||
*
|
||
* @return bool Whether a tag was found before the end of the document.
|
||
*/
|
||
private function parse_next_tag() {
|
||
$this->after_tag();
|
||
|
||
$html = $this->html;
|
||
$doc_length = strlen( $html );
|
||
$was_at = $this->bytes_already_parsed;
|
||
$at = $was_at;
|
||
|
||
while ( false !== $at && $at < $doc_length ) {
|
||
$at = strpos( $html, '<', $at );
|
||
|
||
/*
|
||
* This does not imply an incomplete parse; it indicates that there
|
||
* can be nothing left in the document other than a #text node.
|
||
*/
|
||
if ( false === $at ) {
|
||
$this->parser_state = self::STATE_TEXT_NODE;
|
||
$this->token_starts_at = $was_at;
|
||
$this->token_length = strlen( $html ) - $was_at;
|
||
$this->text_starts_at = $was_at;
|
||
$this->text_length = $this->token_length;
|
||
$this->bytes_already_parsed = strlen( $html );
|
||
return true;
|
||
}
|
||
|
||
if ( $at > $was_at ) {
|
||
/*
|
||
* A "<" has been found in the document. That may be the start of another node, or
|
||
* it may be an "ivalid-first-character-of-tag-name" error. If this is not the start
|
||
* of another node the "<" should be included in this text node and another
|
||
* termination point should be found for the text node.
|
||
*
|
||
* @see https://html.spec.whatwg.org/#tag-open-state
|
||
*/
|
||
if ( strlen( $html ) > $at + 1 ) {
|
||
$next_character = $html[ $at + 1 ];
|
||
$at_another_node =
|
||
'!' === $next_character ||
|
||
'/' === $next_character ||
|
||
'?' === $next_character ||
|
||
( 'A' <= $next_character && $next_character <= 'z' );
|
||
if ( ! $at_another_node ) {
|
||
++$at;
|
||
continue;
|
||
}
|
||
}
|
||
|
||
$this->parser_state = self::STATE_TEXT_NODE;
|
||
$this->token_starts_at = $was_at;
|
||
$this->token_length = $at - $was_at;
|
||
$this->text_starts_at = $was_at;
|
||
$this->text_length = $this->token_length;
|
||
$this->bytes_already_parsed = $at;
|
||
return true;
|
||
}
|
||
|
||
$this->token_starts_at = $at;
|
||
|
||
if ( $at + 1 < $doc_length && '/' === $this->html[ $at + 1 ] ) {
|
||
$this->is_closing_tag = true;
|
||
++$at;
|
||
} else {
|
||
$this->is_closing_tag = false;
|
||
}
|
||
|
||
/*
|
||
* HTML tag names must start with [a-zA-Z] otherwise they are not tags.
|
||
* For example, "<3" is rendered as text, not a tag opener. If at least
|
||
* one letter follows the "<" then _it is_ a tag, but if the following
|
||
* character is anything else it _is not a tag_.
|
||
*
|
||
* It's not uncommon to find non-tags starting with `<` in an HTML
|
||
* document, so it's good for performance to make this pre-check before
|
||
* continuing to attempt to parse a tag name.
|
||
*
|
||
* Reference:
|
||
* * https://html.spec.whatwg.org/multipage/parsing.html#data-state
|
||
* * https://html.spec.whatwg.org/multipage/parsing.html#tag-open-state
|
||
*/
|
||
$tag_name_prefix_length = strspn( $html, 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ', $at + 1 );
|
||
if ( $tag_name_prefix_length > 0 ) {
|
||
++$at;
|
||
$this->parser_state = self::STATE_MATCHED_TAG;
|
||
$this->tag_name_starts_at = $at;
|
||
$this->tag_name_length = $tag_name_prefix_length + strcspn( $html, " \t\f\r\n/>", $at + $tag_name_prefix_length );
|
||
$this->bytes_already_parsed = $at + $this->tag_name_length;
|
||
return true;
|
||
}
|
||
|
||
/*
|
||
* Abort if no tag is found before the end of
|
||
* the document. There is nothing left to parse.
|
||
*/
|
||
if ( $at + 1 >= $doc_length ) {
|
||
$this->parser_state = self::STATE_INCOMPLETE_INPUT;
|
||
|
||
return false;
|
||
}
|
||
|
||
/*
|
||
* `<!` transitions to markup declaration open state
|
||
* https://html.spec.whatwg.org/multipage/parsing.html#markup-declaration-open-state
|
||
*/
|
||
if ( '!' === $html[ $at + 1 ] ) {
|
||
/*
|
||
* `<!--` transitions to a comment state – apply further comment rules.
|
||
* https://html.spec.whatwg.org/multipage/parsing.html#tag-open-state
|
||
*/
|
||
if (
|
||
$doc_length > $at + 3 &&
|
||
'-' === $html[ $at + 2 ] &&
|
||
'-' === $html[ $at + 3 ]
|
||
) {
|
||
$closer_at = $at + 4;
|
||
// If it's not possible to close the comment then there is nothing more to scan.
|
||
if ( $doc_length <= $closer_at ) {
|
||
$this->parser_state = self::STATE_INCOMPLETE_INPUT;
|
||
|
||
return false;
|
||
}
|
||
|
||
// Abruptly-closed empty comments are a sequence of dashes followed by `>`.
|
||
$span_of_dashes = strspn( $html, '-', $closer_at );
|
||
if ( '>' === $html[ $closer_at + $span_of_dashes ] ) {
|
||
/*
|
||
* @todo When implementing `set_modifiable_text()` ensure that updates to this token
|
||
* don't break the syntax for short comments, e.g. `<!--->`. Unlike other comment
|
||
* and bogus comment syntax, these leave no clear insertion point for text and
|
||
* they need to be modified specially in order to contain text. E.g. to store
|
||
* `?` as the modifiable text, the `<!--->` needs to become `<!--?-->`, which
|
||
* involves inserting an additional `-` into the token after the modifiable text.
|
||
*/
|
||
$this->parser_state = self::STATE_COMMENT;
|
||
$this->comment_type = self::COMMENT_AS_ABRUPTLY_CLOSED_COMMENT;
|
||
$this->token_length = $closer_at + $span_of_dashes + 1 - $this->token_starts_at;
|
||
|
||
// Only provide modifiable text if the token is long enough to contain it.
|
||
if ( $span_of_dashes >= 2 ) {
|
||
$this->comment_type = self::COMMENT_AS_HTML_COMMENT;
|
||
$this->text_starts_at = $this->token_starts_at + 4;
|
||
$this->text_length = $span_of_dashes - 2;
|
||
}
|
||
|
||
$this->bytes_already_parsed = $closer_at + $span_of_dashes + 1;
|
||
return true;
|
||
}
|
||
|
||
/*
|
||
* Comments may be closed by either a --> or an invalid --!>.
|
||
* The first occurrence closes the comment.
|
||
*
|
||
* See https://html.spec.whatwg.org/#parse-error-incorrectly-closed-comment
|
||
*/
|
||
--$closer_at; // Pre-increment inside condition below reduces risk of accidental infinite looping.
|
||
while ( ++$closer_at < $doc_length ) {
|
||
$closer_at = strpos( $html, '--', $closer_at );
|
||
if ( false === $closer_at ) {
|
||
$this->parser_state = self::STATE_INCOMPLETE_INPUT;
|
||
|
||
return false;
|
||
}
|
||
|
||
if ( $closer_at + 2 < $doc_length && '>' === $html[ $closer_at + 2 ] ) {
|
||
$this->parser_state = self::STATE_COMMENT;
|
||
$this->comment_type = self::COMMENT_AS_HTML_COMMENT;
|
||
$this->token_length = $closer_at + 3 - $this->token_starts_at;
|
||
$this->text_starts_at = $this->token_starts_at + 4;
|
||
$this->text_length = $closer_at - $this->text_starts_at;
|
||
$this->bytes_already_parsed = $closer_at + 3;
|
||
return true;
|
||
}
|
||
|
||
if (
|
||
$closer_at + 3 < $doc_length &&
|
||
'!' === $html[ $closer_at + 2 ] &&
|
||
'>' === $html[ $closer_at + 3 ]
|
||
) {
|
||
$this->parser_state = self::STATE_COMMENT;
|
||
$this->comment_type = self::COMMENT_AS_HTML_COMMENT;
|
||
$this->token_length = $closer_at + 4 - $this->token_starts_at;
|
||
$this->text_starts_at = $this->token_starts_at + 4;
|
||
$this->text_length = $closer_at - $this->text_starts_at;
|
||
$this->bytes_already_parsed = $closer_at + 4;
|
||
return true;
|
||
}
|
||
}
|
||
}
|
||
|
||
/*
|
||
* `<!DOCTYPE` transitions to DOCTYPE state – skip to the nearest >
|
||
* These are ASCII-case-insensitive.
|
||
* https://html.spec.whatwg.org/multipage/parsing.html#tag-open-state
|
||
*/
|
||
if (
|
||
$doc_length > $at + 8 &&
|
||
( 'D' === $html[ $at + 2 ] || 'd' === $html[ $at + 2 ] ) &&
|
||
( 'O' === $html[ $at + 3 ] || 'o' === $html[ $at + 3 ] ) &&
|
||
( 'C' === $html[ $at + 4 ] || 'c' === $html[ $at + 4 ] ) &&
|
||
( 'T' === $html[ $at + 5 ] || 't' === $html[ $at + 5 ] ) &&
|
||
( 'Y' === $html[ $at + 6 ] || 'y' === $html[ $at + 6 ] ) &&
|
||
( 'P' === $html[ $at + 7 ] || 'p' === $html[ $at + 7 ] ) &&
|
||
( 'E' === $html[ $at + 8 ] || 'e' === $html[ $at + 8 ] )
|
||
) {
|
||
$closer_at = strpos( $html, '>', $at + 9 );
|
||
if ( false === $closer_at ) {
|
||
$this->parser_state = self::STATE_INCOMPLETE_INPUT;
|
||
|
||
return false;
|
||
}
|
||
|
||
$this->parser_state = self::STATE_DOCTYPE;
|
||
$this->token_length = $closer_at + 1 - $this->token_starts_at;
|
||
$this->text_starts_at = $this->token_starts_at + 9;
|
||
$this->text_length = $closer_at - $this->text_starts_at;
|
||
$this->bytes_already_parsed = $closer_at + 1;
|
||
return true;
|
||
}
|
||
|
||
/*
|
||
* Anything else here is an incorrectly-opened comment and transitions
|
||
* to the bogus comment state - skip to the nearest >. If no closer is
|
||
* found then the HTML was truncated inside the markup declaration.
|
||
*/
|
||
$closer_at = strpos( $html, '>', $at + 1 );
|
||
if ( false === $closer_at ) {
|
||
$this->parser_state = self::STATE_INCOMPLETE_INPUT;
|
||
|
||
return false;
|
||
}
|
||
|
||
$this->parser_state = self::STATE_COMMENT;
|
||
$this->comment_type = self::COMMENT_AS_INVALID_HTML;
|
||
$this->token_length = $closer_at + 1 - $this->token_starts_at;
|
||
$this->text_starts_at = $this->token_starts_at + 2;
|
||
$this->text_length = $closer_at - $this->text_starts_at;
|
||
$this->bytes_already_parsed = $closer_at + 1;
|
||
|
||
/*
|
||
* Identify nodes that would be CDATA if HTML had CDATA sections.
|
||
*
|
||
* This section must occur after identifying the bogus comment end
|
||
* because in an HTML parser it will span to the nearest `>`, even
|
||
* if there's no `]]>` as would be required in an XML document. It
|
||
* is therefore not possible to parse a CDATA section containing
|
||
* a `>` in the HTML syntax.
|
||
*
|
||
* Inside foreign elements there is a discrepancy between browsers
|
||
* and the specification on this.
|
||
*
|
||
* @todo Track whether the Tag Processor is inside a foreign element
|
||
* and require the proper closing `]]>` in those cases.
|
||
*/
|
||
if (
|
||
$this->token_length >= 10 &&
|
||
'[' === $html[ $this->token_starts_at + 2 ] &&
|
||
'C' === $html[ $this->token_starts_at + 3 ] &&
|
||
'D' === $html[ $this->token_starts_at + 4 ] &&
|
||
'A' === $html[ $this->token_starts_at + 5 ] &&
|
||
'T' === $html[ $this->token_starts_at + 6 ] &&
|
||
'A' === $html[ $this->token_starts_at + 7 ] &&
|
||
'[' === $html[ $this->token_starts_at + 8 ] &&
|
||
']' === $html[ $closer_at - 1 ] &&
|
||
']' === $html[ $closer_at - 2 ]
|
||
) {
|
||
$this->parser_state = self::STATE_COMMENT;
|
||
$this->comment_type = self::COMMENT_AS_CDATA_LOOKALIKE;
|
||
$this->text_starts_at += 7;
|
||
$this->text_length -= 9;
|
||
}
|
||
|
||
return true;
|
||
}
|
||
|
||
/*
|
||
* </> is a missing end tag name, which is ignored.
|
||
*
|
||
* This was also known as the "presumptuous empty tag"
|
||
* in early discussions as it was proposed to close
|
||
* the nearest previous opening tag.
|
||
*
|
||
* See https://html.spec.whatwg.org/#parse-error-missing-end-tag-name
|
||
*/
|
||
if ( '>' === $html[ $at + 1 ] ) {
|
||
$this->parser_state = self::STATE_PRESUMPTUOUS_TAG;
|
||
$this->token_length = $at + 2 - $this->token_starts_at;
|
||
$this->bytes_already_parsed = $at + 2;
|
||
return true;
|
||
}
|
||
|
||
/*
|
||
* `<?` transitions to a bogus comment state – skip to the nearest >
|
||
* See https://html.spec.whatwg.org/multipage/parsing.html#tag-open-state
|
||
*/
|
||
if ( '?' === $html[ $at + 1 ] ) {
|
||
$closer_at = strpos( $html, '>', $at + 2 );
|
||
if ( false === $closer_at ) {
|
||
$this->parser_state = self::STATE_INCOMPLETE_INPUT;
|
||
|
||
return false;
|
||
}
|
||
|
||
$this->parser_state = self::STATE_COMMENT;
|
||
$this->comment_type = self::COMMENT_AS_INVALID_HTML;
|
||
$this->token_length = $closer_at + 1 - $this->token_starts_at;
|
||
$this->text_starts_at = $this->token_starts_at + 2;
|
||
$this->text_length = $closer_at - $this->text_starts_at;
|
||
$this->bytes_already_parsed = $closer_at + 1;
|
||
|
||
/*
|
||
* Identify a Processing Instruction node were HTML to have them.
|
||
*
|
||
* This section must occur after identifying the bogus comment end
|
||
* because in an HTML parser it will span to the nearest `>`, even
|
||
* if there's no `?>` as would be required in an XML document. It
|
||
* is therefore not possible to parse a Processing Instruction node
|
||
* containing a `>` in the HTML syntax.
|
||
*
|
||
* XML allows for more target names, but this code only identifies
|
||
* those with ASCII-representable target names. This means that it
|
||
* may identify some Processing Instruction nodes as bogus comments,
|
||
* but it will not misinterpret the HTML structure. By limiting the
|
||
* identification to these target names the Tag Processor can avoid
|
||
* the need to start parsing UTF-8 sequences.
|
||
*
|
||
* > NameStartChar ::= ":" | [A-Z] | "_" | [a-z] | [#xC0-#xD6] | [#xD8-#xF6] | [#xF8-#x2FF] |
|
||
* [#x370-#x37D] | [#x37F-#x1FFF] | [#x200C-#x200D] | [#x2070-#x218F] |
|
||
* [#x2C00-#x2FEF] | [#x3001-#xD7FF] | [#xF900-#xFDCF] | [#xFDF0-#xFFFD] |
|
||
* [#x10000-#xEFFFF]
|
||
* > NameChar ::= NameStartChar | "-" | "." | [0-9] | #xB7 | [#x0300-#x036F] | [#x203F-#x2040]
|
||
*
|
||
* @see https://www.w3.org/TR/2006/REC-xml11-20060816/#NT-PITarget
|
||
*/
|
||
if ( $this->token_length >= 5 && '?' === $html[ $closer_at - 1 ] ) {
|
||
$comment_text = substr( $html, $this->token_starts_at + 2, $this->token_length - 4 );
|
||
$pi_target_length = strspn( $comment_text, 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ:_' );
|
||
|
||
if ( 0 < $pi_target_length ) {
|
||
$pi_target_length += strspn( $comment_text, 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789:_-.', $pi_target_length );
|
||
|
||
$this->comment_type = self::COMMENT_AS_PI_NODE_LOOKALIKE;
|
||
$this->tag_name_starts_at = $this->token_starts_at + 2;
|
||
$this->tag_name_length = $pi_target_length;
|
||
$this->text_starts_at += $pi_target_length;
|
||
$this->text_length -= $pi_target_length + 1;
|
||
}
|
||
}
|
||
|
||
return true;
|
||
}
|
||
|
||
/*
|
||
* If a non-alpha starts the tag name in a tag closer it's a comment.
|
||
* Find the first `>`, which closes the comment.
|
||
*
|
||
* This parser classifies these particular comments as special "funky comments"
|
||
* which are made available for further processing.
|
||
*
|
||
* See https://html.spec.whatwg.org/#parse-error-invalid-first-character-of-tag-name
|
||
*/
|
||
if ( $this->is_closing_tag ) {
|
||
// No chance of finding a closer.
|
||
if ( $at + 3 > $doc_length ) {
|
||
return false;
|
||
}
|
||
|
||
$closer_at = strpos( $html, '>', $at + 3 );
|
||
if ( false === $closer_at ) {
|
||
$this->parser_state = self::STATE_INCOMPLETE_INPUT;
|
||
|
||
return false;
|
||
}
|
||
|
||
$this->parser_state = self::STATE_FUNKY_COMMENT;
|
||
$this->token_length = $closer_at + 1 - $this->token_starts_at;
|
||
$this->text_starts_at = $this->token_starts_at + 2;
|
||
$this->text_length = $closer_at - $this->text_starts_at;
|
||
$this->bytes_already_parsed = $closer_at + 1;
|
||
return true;
|
||
}
|
||
|
||
++$at;
|
||
}
|
||
|
||
return false;
|
||
}
|
||
|
||
/**
|
||
* Parses the next attribute.
|
||
*
|
||
* @since 6.2.0
|
||
*
|
||
* @return bool Whether an attribute was found before the end of the document.
|
||
*/
|
||
private function parse_next_attribute() {
|
||
// Skip whitespace and slashes.
|
||
$this->bytes_already_parsed += strspn( $this->html, " \t\f\r\n/", $this->bytes_already_parsed );
|
||
if ( $this->bytes_already_parsed >= strlen( $this->html ) ) {
|
||
$this->parser_state = self::STATE_INCOMPLETE_INPUT;
|
||
|
||
return false;
|
||
}
|
||
|
||
/*
|
||
* Treat the equal sign as a part of the attribute
|
||
* name if it is the first encountered byte.
|
||
*
|
||
* @see https://html.spec.whatwg.org/multipage/parsing.html#before-attribute-name-state
|
||
*/
|
||
$name_length = '=' === $this->html[ $this->bytes_already_parsed ]
|
||
? 1 + strcspn( $this->html, "=/> \t\f\r\n", $this->bytes_already_parsed + 1 )
|
||
: strcspn( $this->html, "=/> \t\f\r\n", $this->bytes_already_parsed );
|
||
|
||
// No attribute, just tag closer.
|
||
if ( 0 === $name_length || $this->bytes_already_parsed + $name_length >= strlen( $this->html ) ) {
|
||
return false;
|
||
}
|
||
|
||
$attribute_start = $this->bytes_already_parsed;
|
||
$attribute_name = substr( $this->html, $attribute_start, $name_length );
|
||
$this->bytes_already_parsed += $name_length;
|
||
if ( $this->bytes_already_parsed >= strlen( $this->html ) ) {
|
||
$this->parser_state = self::STATE_INCOMPLETE_INPUT;
|
||
|
||
return false;
|
||
}
|
||
|
||
$this->skip_whitespace();
|
||
if ( $this->bytes_already_parsed >= strlen( $this->html ) ) {
|
||
$this->parser_state = self::STATE_INCOMPLETE_INPUT;
|
||
|
||
return false;
|
||
}
|
||
|
||
$has_value = '=' === $this->html[ $this->bytes_already_parsed ];
|
||
if ( $has_value ) {
|
||
++$this->bytes_already_parsed;
|
||
$this->skip_whitespace();
|
||
if ( $this->bytes_already_parsed >= strlen( $this->html ) ) {
|
||
$this->parser_state = self::STATE_INCOMPLETE_INPUT;
|
||
|
||
return false;
|
||
}
|
||
|
||
switch ( $this->html[ $this->bytes_already_parsed ] ) {
|
||
case "'":
|
||
case '"':
|
||
$quote = $this->html[ $this->bytes_already_parsed ];
|
||
$value_start = $this->bytes_already_parsed + 1;
|
||
$value_length = strcspn( $this->html, $quote, $value_start );
|
||
$attribute_end = $value_start + $value_length + 1;
|
||
$this->bytes_already_parsed = $attribute_end;
|
||
break;
|
||
|
||
default:
|
||
$value_start = $this->bytes_already_parsed;
|
||
$value_length = strcspn( $this->html, "> \t\f\r\n", $value_start );
|
||
$attribute_end = $value_start + $value_length;
|
||
$this->bytes_already_parsed = $attribute_end;
|
||
}
|
||
} else {
|
||
$value_start = $this->bytes_already_parsed;
|
||
$value_length = 0;
|
||
$attribute_end = $attribute_start + $name_length;
|
||
}
|
||
|
||
if ( $attribute_end >= strlen( $this->html ) ) {
|
||
$this->parser_state = self::STATE_INCOMPLETE_INPUT;
|
||
|
||
return false;
|
||
}
|
||
|
||
if ( $this->is_closing_tag ) {
|
||
return true;
|
||
}
|
||
|
||
/*
|
||
* > There must never be two or more attributes on
|
||
* > the same start tag whose names are an ASCII
|
||
* > case-insensitive match for each other.
|
||
* - HTML 5 spec
|
||
*
|
||
* @see https://html.spec.whatwg.org/multipage/syntax.html#attributes-2:ascii-case-insensitive
|
||
*/
|
||
$comparable_name = strtolower( $attribute_name );
|
||
|
||
// If an attribute is listed many times, only use the first declaration and ignore the rest.
|
||
if ( ! array_key_exists( $comparable_name, $this->attributes ) ) {
|
||
$this->attributes[ $comparable_name ] = new WP_HTML_Attribute_Token(
|
||
$attribute_name,
|
||
$value_start,
|
||
$value_length,
|
||
$attribute_start,
|
||
$attribute_end - $attribute_start,
|
||
! $has_value
|
||
);
|
||
|
||
return true;
|
||
}
|
||
|
||
/*
|
||
* Track the duplicate attributes so if we remove it, all disappear together.
|
||
*
|
||
* While `$this->duplicated_attributes` could always be stored as an `array()`,
|
||
* which would simplify the logic here, storing a `null` and only allocating
|
||
* an array when encountering duplicates avoids needless allocations in the
|
||
* normative case of parsing tags with no duplicate attributes.
|
||
*/
|
||
$duplicate_span = new WP_HTML_Span( $attribute_start, $attribute_end - $attribute_start );
|
||
if ( null === $this->duplicate_attributes ) {
|
||
$this->duplicate_attributes = array( $comparable_name => array( $duplicate_span ) );
|
||
} elseif ( ! array_key_exists( $comparable_name, $this->duplicate_attributes ) ) {
|
||
$this->duplicate_attributes[ $comparable_name ] = array( $duplicate_span );
|
||
} else {
|
||
$this->duplicate_attributes[ $comparable_name ][] = $duplicate_span;
|
||
}
|
||
|
||
return true;
|
||
}
|
||
|
||
/**
|
||
* Move the internal cursor past any immediate successive whitespace.
|
||
*
|
||
* @since 6.2.0
|
||
*/
|
||
private function skip_whitespace() {
|
||
$this->bytes_already_parsed += strspn( $this->html, " \t\f\r\n", $this->bytes_already_parsed );
|
||
}
|
||
|
||
/**
|
||
* Applies attribute updates and cleans up once a tag is fully parsed.
|
||
*
|
||
* @since 6.2.0
|
||
*/
|
||
private function after_tag() {
|
||
$this->token_starts_at = null;
|
||
$this->token_length = null;
|
||
$this->tag_name_starts_at = null;
|
||
$this->tag_name_length = null;
|
||
$this->text_starts_at = 0;
|
||
$this->text_length = 0;
|
||
$this->is_closing_tag = null;
|
||
$this->attributes = array();
|
||
$this->comment_type = null;
|
||
$this->duplicate_attributes = null;
|
||
}
|
||
|
||
/**
|
||
* Converts class name updates into tag attributes updates
|
||
* (they are accumulated in different data formats for performance).
|
||
*
|
||
* @since 6.2.0
|
||
*
|
||
* @see WP_HTML_Tag_Processor::$lexical_updates
|
||
* @see WP_HTML_Tag_Processor::$classname_updates
|
||
*/
|
||
private function class_name_updates_to_attributes_updates() {
|
||
if ( count( $this->classname_updates ) === 0 ) {
|
||
return;
|
||
}
|
||
|
||
$existing_class = $this->get_enqueued_attribute_value( 'class' );
|
||
if ( null === $existing_class || true === $existing_class ) {
|
||
$existing_class = '';
|
||
}
|
||
|
||
if ( false === $existing_class && isset( $this->attributes['class'] ) ) {
|
||
$existing_class = substr(
|
||
$this->html,
|
||
$this->attributes['class']->value_starts_at,
|
||
$this->attributes['class']->value_length
|
||
);
|
||
}
|
||
|
||
if ( false === $existing_class ) {
|
||
$existing_class = '';
|
||
}
|
||
|
||
/**
|
||
* Updated "class" attribute value.
|
||
*
|
||
* This is incrementally built while scanning through the existing class
|
||
* attribute, skipping removed classes on the way, and then appending
|
||
* added classes at the end. Only when finished processing will the
|
||
* value contain the final new value.
|
||
|
||
* @var string $class
|
||
*/
|
||
$class = '';
|
||
|
||
/**
|
||
* Tracks the cursor position in the existing
|
||
* class attribute value while parsing.
|
||
*
|
||
* @var int $at
|
||
*/
|
||
$at = 0;
|
||
|
||
/**
|
||
* Indicates if there's any need to modify the existing class attribute.
|
||
*
|
||
* If a call to `add_class()` and `remove_class()` wouldn't impact
|
||
* the `class` attribute value then there's no need to rebuild it.
|
||
* For example, when adding a class that's already present or
|
||
* removing one that isn't.
|
||
*
|
||
* This flag enables a performance optimization when none of the enqueued
|
||
* class updates would impact the `class` attribute; namely, that the
|
||
* processor can continue without modifying the input document, as if
|
||
* none of the `add_class()` or `remove_class()` calls had been made.
|
||
*
|
||
* This flag is set upon the first change that requires a string update.
|
||
*
|
||
* @var bool $modified
|
||
*/
|
||
$modified = false;
|
||
|
||
// Remove unwanted classes by only copying the new ones.
|
||
$existing_class_length = strlen( $existing_class );
|
||
while ( $at < $existing_class_length ) {
|
||
// Skip to the first non-whitespace character.
|
||
$ws_at = $at;
|
||
$ws_length = strspn( $existing_class, " \t\f\r\n", $ws_at );
|
||
$at += $ws_length;
|
||
|
||
// Capture the class name – it's everything until the next whitespace.
|
||
$name_length = strcspn( $existing_class, " \t\f\r\n", $at );
|
||
if ( 0 === $name_length ) {
|
||
// If no more class names are found then that's the end.
|
||
break;
|
||
}
|
||
|
||
$name = substr( $existing_class, $at, $name_length );
|
||
$at += $name_length;
|
||
|
||
// If this class is marked for removal, start processing the next one.
|
||
$remove_class = (
|
||
isset( $this->classname_updates[ $name ] ) &&
|
||
self::REMOVE_CLASS === $this->classname_updates[ $name ]
|
||
);
|
||
|
||
// If a class has already been seen then skip it; it should not be added twice.
|
||
if ( ! $remove_class ) {
|
||
$this->classname_updates[ $name ] = self::SKIP_CLASS;
|
||
}
|
||
|
||
if ( $remove_class ) {
|
||
$modified = true;
|
||
continue;
|
||
}
|
||
|
||
/*
|
||
* Otherwise, append it to the new "class" attribute value.
|
||
*
|
||
* There are options for handling whitespace between tags.
|
||
* Preserving the existing whitespace produces fewer changes
|
||
* to the HTML content and should clarify the before/after
|
||
* content when debugging the modified output.
|
||
*
|
||
* This approach contrasts normalizing the inter-class
|
||
* whitespace to a single space, which might appear cleaner
|
||
* in the output HTML but produce a noisier change.
|
||
*/
|
||
$class .= substr( $existing_class, $ws_at, $ws_length );
|
||
$class .= $name;
|
||
}
|
||
|
||
// Add new classes by appending those which haven't already been seen.
|
||
foreach ( $this->classname_updates as $name => $operation ) {
|
||
if ( self::ADD_CLASS === $operation ) {
|
||
$modified = true;
|
||
|
||
$class .= strlen( $class ) > 0 ? ' ' : '';
|
||
$class .= $name;
|
||
}
|
||
}
|
||
|
||
$this->classname_updates = array();
|
||
if ( ! $modified ) {
|
||
return;
|
||
}
|
||
|
||
if ( strlen( $class ) > 0 ) {
|
||
$this->set_attribute( 'class', $class );
|
||
} else {
|
||
$this->remove_attribute( 'class' );
|
||
}
|
||
}
|
||
|
||
/**
|
||
* Applies attribute updates to HTML document.
|
||
*
|
||
* @since 6.2.0
|
||
* @since 6.2.1 Accumulates shift for internal cursor and passed pointer.
|
||
* @since 6.3.0 Invalidate any bookmarks whose targets are overwritten.
|
||
*
|
||
* @param int $shift_this_point Accumulate and return shift for this position.
|
||
* @return int How many bytes the given pointer moved in response to the updates.
|
||
*/
|
||
private function apply_attributes_updates( $shift_this_point = 0 ) {
|
||
if ( ! count( $this->lexical_updates ) ) {
|
||
return 0;
|
||
}
|
||
|
||
$accumulated_shift_for_given_point = 0;
|
||
|
||
/*
|
||
* Attribute updates can be enqueued in any order but updates
|
||
* to the document must occur in lexical order; that is, each
|
||
* replacement must be made before all others which follow it
|
||
* at later string indices in the input document.
|
||
*
|
||
* Sorting avoid making out-of-order replacements which
|
||
* can lead to mangled output, partially-duplicated
|
||
* attributes, and overwritten attributes.
|
||
*/
|
||
usort( $this->lexical_updates, array( self::class, 'sort_start_ascending' ) );
|
||
|
||
$bytes_already_copied = 0;
|
||
$output_buffer = '';
|
||
foreach ( $this->lexical_updates as $diff ) {
|
||
$shift = strlen( $diff->text ) - $diff->length;
|
||
|
||
// Adjust the cursor position by however much an update affects it.
|
||
if ( $diff->start <= $this->bytes_already_parsed ) {
|
||
$this->bytes_already_parsed += $shift;
|
||
}
|
||
|
||
// Accumulate shift of the given pointer within this function call.
|
||
if ( $diff->start <= $shift_this_point ) {
|
||
$accumulated_shift_for_given_point += $shift;
|
||
}
|
||
|
||
$output_buffer .= substr( $this->html, $bytes_already_copied, $diff->start - $bytes_already_copied );
|
||
$output_buffer .= $diff->text;
|
||
$bytes_already_copied = $diff->start + $diff->length;
|
||
}
|
||
|
||
$this->html = $output_buffer . substr( $this->html, $bytes_already_copied );
|
||
|
||
/*
|
||
* Adjust bookmark locations to account for how the text
|
||
* replacements adjust offsets in the input document.
|
||
*/
|
||
foreach ( $this->bookmarks as $bookmark_name => $bookmark ) {
|
||
$bookmark_end = $bookmark->start + $bookmark->length;
|
||
|
||
/*
|
||
* Each lexical update which appears before the bookmark's endpoints
|
||
* might shift the offsets for those endpoints. Loop through each change
|
||
* and accumulate the total shift for each bookmark, then apply that
|
||
* shift after tallying the full delta.
|
||
*/
|
||
$head_delta = 0;
|
||
$tail_delta = 0;
|
||
|
||
foreach ( $this->lexical_updates as $diff ) {
|
||
$diff_end = $diff->start + $diff->length;
|
||
|
||
if ( $bookmark->start < $diff->start && $bookmark_end < $diff->start ) {
|
||
break;
|
||
}
|
||
|
||
if ( $bookmark->start >= $diff->start && $bookmark_end < $diff_end ) {
|
||
$this->release_bookmark( $bookmark_name );
|
||
continue 2;
|
||
}
|
||
|
||
$delta = strlen( $diff->text ) - $diff->length;
|
||
|
||
if ( $bookmark->start >= $diff->start ) {
|
||
$head_delta += $delta;
|
||
}
|
||
|
||
if ( $bookmark_end >= $diff_end ) {
|
||
$tail_delta += $delta;
|
||
}
|
||
}
|
||
|
||
$bookmark->start += $head_delta;
|
||
$bookmark->length += $tail_delta - $head_delta;
|
||
}
|
||
|
||
$this->lexical_updates = array();
|
||
|
||
return $accumulated_shift_for_given_point;
|
||
}
|
||
|
||
/**
|
||
* Checks whether a bookmark with the given name exists.
|
||
*
|
||
* @since 6.3.0
|
||
*
|
||
* @param string $bookmark_name Name to identify a bookmark that potentially exists.
|
||
* @return bool Whether that bookmark exists.
|
||
*/
|
||
public function has_bookmark( $bookmark_name ) {
|
||
return array_key_exists( $bookmark_name, $this->bookmarks );
|
||
}
|
||
|
||
/**
|
||
* Move the internal cursor in the Tag Processor to a given bookmark's location.
|
||
*
|
||
* In order to prevent accidental infinite loops, there's a
|
||
* maximum limit on the number of times seek() can be called.
|
||
*
|
||
* @since 6.2.0
|
||
*
|
||
* @param string $bookmark_name Jump to the place in the document identified by this bookmark name.
|
||
* @return bool Whether the internal cursor was successfully moved to the bookmark's location.
|
||
*/
|
||
public function seek( $bookmark_name ) {
|
||
if ( ! array_key_exists( $bookmark_name, $this->bookmarks ) ) {
|
||
_doing_it_wrong(
|
||
__METHOD__,
|
||
__( 'Unknown bookmark name.' ),
|
||
'6.2.0'
|
||
);
|
||
return false;
|
||
}
|
||
|
||
if ( ++$this->seek_count > static::MAX_SEEK_OPS ) {
|
||
_doing_it_wrong(
|
||
__METHOD__,
|
||
__( 'Too many calls to seek() - this can lead to performance issues.' ),
|
||
'6.2.0'
|
||
);
|
||
return false;
|
||
}
|
||
|
||
// Flush out any pending updates to the document.
|
||
$this->get_updated_html();
|
||
|
||
// Point this tag processor before the sought tag opener and consume it.
|
||
$this->bytes_already_parsed = $this->bookmarks[ $bookmark_name ]->start;
|
||
return $this->next_token();
|
||
}
|
||
|
||
/**
|
||
* Compare two WP_HTML_Text_Replacement objects.
|
||
*
|
||
* @since 6.2.0
|
||
*
|
||
* @param WP_HTML_Text_Replacement $a First attribute update.
|
||
* @param WP_HTML_Text_Replacement $b Second attribute update.
|
||
* @return int Comparison value for string order.
|
||
*/
|
||
private static function sort_start_ascending( $a, $b ) {
|
||
$by_start = $a->start - $b->start;
|
||
if ( 0 !== $by_start ) {
|
||
return $by_start;
|
||
}
|
||
|
||
$by_text = isset( $a->text, $b->text ) ? strcmp( $a->text, $b->text ) : 0;
|
||
if ( 0 !== $by_text ) {
|
||
return $by_text;
|
||
}
|
||
|
||
/*
|
||
* This code should be unreachable, because it implies the two replacements
|
||
* start at the same location and contain the same text.
|
||
*/
|
||
return $a->length - $b->length;
|
||
}
|
||
|
||
/**
|
||
* Return the enqueued value for a given attribute, if one exists.
|
||
*
|
||
* Enqueued updates can take different data types:
|
||
* - If an update is enqueued and is boolean, the return will be `true`
|
||
* - If an update is otherwise enqueued, the return will be the string value of that update.
|
||
* - If an attribute is enqueued to be removed, the return will be `null` to indicate that.
|
||
* - If no updates are enqueued, the return will be `false` to differentiate from "removed."
|
||
*
|
||
* @since 6.2.0
|
||
*
|
||
* @param string $comparable_name The attribute name in its comparable form.
|
||
* @return string|boolean|null Value of enqueued update if present, otherwise false.
|
||
*/
|
||
private function get_enqueued_attribute_value( $comparable_name ) {
|
||
if ( self::STATE_MATCHED_TAG !== $this->parser_state ) {
|
||
return false;
|
||
}
|
||
|
||
if ( ! isset( $this->lexical_updates[ $comparable_name ] ) ) {
|
||
return false;
|
||
}
|
||
|
||
$enqueued_text = $this->lexical_updates[ $comparable_name ]->text;
|
||
|
||
// Removed attributes erase the entire span.
|
||
if ( '' === $enqueued_text ) {
|
||
return null;
|
||
}
|
||
|
||
/*
|
||
* Boolean attribute updates are just the attribute name without a corresponding value.
|
||
*
|
||
* This value might differ from the given comparable name in that there could be leading
|
||
* or trailing whitespace, and that the casing follows the name given in `set_attribute`.
|
||
*
|
||
* Example:
|
||
*
|
||
* $p->set_attribute( 'data-TEST-id', 'update' );
|
||
* 'update' === $p->get_enqueued_attribute_value( 'data-test-id' );
|
||
*
|
||
* Detect this difference based on the absence of the `=`, which _must_ exist in any
|
||
* attribute containing a value, e.g. `<input type="text" enabled />`.
|
||
* ¹ ²
|
||
* 1. Attribute with a string value.
|
||
* 2. Boolean attribute whose value is `true`.
|
||
*/
|
||
$equals_at = strpos( $enqueued_text, '=' );
|
||
if ( false === $equals_at ) {
|
||
return true;
|
||
}
|
||
|
||
/*
|
||
* Finally, a normal update's value will appear after the `=` and
|
||
* be double-quoted, as performed incidentally by `set_attribute`.
|
||
*
|
||
* e.g. `type="text"`
|
||
* ¹² ³
|
||
* 1. Equals is here.
|
||
* 2. Double-quoting starts one after the equals sign.
|
||
* 3. Double-quoting ends at the last character in the update.
|
||
*/
|
||
$enqueued_value = substr( $enqueued_text, $equals_at + 2, -1 );
|
||
return html_entity_decode( $enqueued_value );
|
||
}
|
||
|
||
/**
|
||
* Returns the value of a requested attribute from a matched tag opener if that attribute exists.
|
||
*
|
||
* Example:
|
||
*
|
||
* $p = new WP_HTML_Tag_Processor( '<div enabled class="test" data-test-id="14">Test</div>' );
|
||
* $p->next_tag( array( 'class_name' => 'test' ) ) === true;
|
||
* $p->get_attribute( 'data-test-id' ) === '14';
|
||
* $p->get_attribute( 'enabled' ) === true;
|
||
* $p->get_attribute( 'aria-label' ) === null;
|
||
*
|
||
* $p->next_tag() === false;
|
||
* $p->get_attribute( 'class' ) === null;
|
||
*
|
||
* @since 6.2.0
|
||
*
|
||
* @param string $name Name of attribute whose value is requested.
|
||
* @return string|true|null Value of attribute or `null` if not available. Boolean attributes return `true`.
|
||
*/
|
||
public function get_attribute( $name ) {
|
||
if ( self::STATE_MATCHED_TAG !== $this->parser_state ) {
|
||
return null;
|
||
}
|
||
|
||
$comparable = strtolower( $name );
|
||
|
||
/*
|
||
* For every attribute other than `class` it's possible to perform a quick check if
|
||
* there's an enqueued lexical update whose value takes priority over what's found in
|
||
* the input document.
|
||
*
|
||
* The `class` attribute is special though because of the exposed helpers `add_class`
|
||
* and `remove_class`. These form a builder for the `class` attribute, so an additional
|
||
* check for enqueued class changes is required in addition to the check for any enqueued
|
||
* attribute values. If any exist, those enqueued class changes must first be flushed out
|
||
* into an attribute value update.
|
||
*/
|
||
if ( 'class' === $name ) {
|
||
$this->class_name_updates_to_attributes_updates();
|
||
}
|
||
|
||
// Return any enqueued attribute value updates if they exist.
|
||
$enqueued_value = $this->get_enqueued_attribute_value( $comparable );
|
||
if ( false !== $enqueued_value ) {
|
||
return $enqueued_value;
|
||
}
|
||
|
||
if ( ! isset( $this->attributes[ $comparable ] ) ) {
|
||
return null;
|
||
}
|
||
|
||
$attribute = $this->attributes[ $comparable ];
|
||
|
||
/*
|
||
* This flag distinguishes an attribute with no value
|
||
* from an attribute with an empty string value. For
|
||
* unquoted attributes this could look very similar.
|
||
* It refers to whether an `=` follows the name.
|
||
*
|
||
* e.g. <div boolean-attribute empty-attribute=></div>
|
||
* ¹ ²
|
||
* 1. Attribute `boolean-attribute` is `true`.
|
||
* 2. Attribute `empty-attribute` is `""`.
|
||
*/
|
||
if ( true === $attribute->is_true ) {
|
||
return true;
|
||
}
|
||
|
||
$raw_value = substr( $this->html, $attribute->value_starts_at, $attribute->value_length );
|
||
|
||
return html_entity_decode( $raw_value );
|
||
}
|
||
|
||
/**
|
||
* Gets lowercase names of all attributes matching a given prefix in the current tag.
|
||
*
|
||
* Note that matching is case-insensitive. This is in accordance with the spec:
|
||
*
|
||
* > There must never be two or more attributes on
|
||
* > the same start tag whose names are an ASCII
|
||
* > case-insensitive match for each other.
|
||
* - HTML 5 spec
|
||
*
|
||
* Example:
|
||
*
|
||
* $p = new WP_HTML_Tag_Processor( '<div data-ENABLED class="test" DATA-test-id="14">Test</div>' );
|
||
* $p->next_tag( array( 'class_name' => 'test' ) ) === true;
|
||
* $p->get_attribute_names_with_prefix( 'data-' ) === array( 'data-enabled', 'data-test-id' );
|
||
*
|
||
* $p->next_tag() === false;
|
||
* $p->get_attribute_names_with_prefix( 'data-' ) === null;
|
||
*
|
||
* @since 6.2.0
|
||
*
|
||
* @see https://html.spec.whatwg.org/multipage/syntax.html#attributes-2:ascii-case-insensitive
|
||
*
|
||
* @param string $prefix Prefix of requested attribute names.
|
||
* @return array|null List of attribute names, or `null` when no tag opener is matched.
|
||
*/
|
||
public function get_attribute_names_with_prefix( $prefix ) {
|
||
if (
|
||
self::STATE_MATCHED_TAG !== $this->parser_state ||
|
||
$this->is_closing_tag
|
||
) {
|
||
return null;
|
||
}
|
||
|
||
$comparable = strtolower( $prefix );
|
||
|
||
$matches = array();
|
||
foreach ( array_keys( $this->attributes ) as $attr_name ) {
|
||
if ( str_starts_with( $attr_name, $comparable ) ) {
|
||
$matches[] = $attr_name;
|
||
}
|
||
}
|
||
return $matches;
|
||
}
|
||
|
||
/**
|
||
* Returns the uppercase name of the matched tag.
|
||
*
|
||
* Example:
|
||
*
|
||
* $p = new WP_HTML_Tag_Processor( '<div class="test">Test</div>' );
|
||
* $p->next_tag() === true;
|
||
* $p->get_tag() === 'DIV';
|
||
*
|
||
* $p->next_tag() === false;
|
||
* $p->get_tag() === null;
|
||
*
|
||
* @since 6.2.0
|
||
*
|
||
* @return string|null Name of currently matched tag in input HTML, or `null` if none found.
|
||
*/
|
||
public function get_tag() {
|
||
if ( null === $this->tag_name_starts_at ) {
|
||
return null;
|
||
}
|
||
|
||
$tag_name = substr( $this->html, $this->tag_name_starts_at, $this->tag_name_length );
|
||
|
||
if ( self::STATE_MATCHED_TAG === $this->parser_state ) {
|
||
return strtoupper( $tag_name );
|
||
}
|
||
|
||
if (
|
||
self::STATE_COMMENT === $this->parser_state &&
|
||
self::COMMENT_AS_PI_NODE_LOOKALIKE === $this->get_comment_type()
|
||
) {
|
||
return $tag_name;
|
||
}
|
||
|
||
return null;
|
||
}
|
||
|
||
/**
|
||
* Indicates if the currently matched tag contains the self-closing flag.
|
||
*
|
||
* No HTML elements ought to have the self-closing flag and for those, the self-closing
|
||
* flag will be ignored. For void elements this is benign because they "self close"
|
||
* automatically. For non-void HTML elements though problems will appear if someone
|
||
* intends to use a self-closing element in place of that element with an empty body.
|
||
* For HTML foreign elements and custom elements the self-closing flag determines if
|
||
* they self-close or not.
|
||
*
|
||
* This function does not determine if a tag is self-closing,
|
||
* but only if the self-closing flag is present in the syntax.
|
||
*
|
||
* @since 6.3.0
|
||
*
|
||
* @return bool Whether the currently matched tag contains the self-closing flag.
|
||
*/
|
||
public function has_self_closing_flag() {
|
||
if ( self::STATE_MATCHED_TAG !== $this->parser_state ) {
|
||
return false;
|
||
}
|
||
|
||
/*
|
||
* The self-closing flag is the solidus at the _end_ of the tag, not the beginning.
|
||
*
|
||
* Example:
|
||
*
|
||
* <figure />
|
||
* ^ this appears one character before the end of the closing ">".
|
||
*/
|
||
return '/' === $this->html[ $this->token_starts_at + $this->token_length - 1 ];
|
||
}
|
||
|
||
/**
|
||
* Indicates if the current tag token is a tag closer.
|
||
*
|
||
* Example:
|
||
*
|
||
* $p = new WP_HTML_Tag_Processor( '<div></div>' );
|
||
* $p->next_tag( array( 'tag_name' => 'div', 'tag_closers' => 'visit' ) );
|
||
* $p->is_tag_closer() === false;
|
||
*
|
||
* $p->next_tag( array( 'tag_name' => 'div', 'tag_closers' => 'visit' ) );
|
||
* $p->is_tag_closer() === true;
|
||
*
|
||
* @since 6.2.0
|
||
*
|
||
* @return bool Whether the current tag is a tag closer.
|
||
*/
|
||
public function is_tag_closer() {
|
||
return (
|
||
self::STATE_MATCHED_TAG === $this->parser_state &&
|
||
$this->is_closing_tag
|
||
);
|
||
}
|
||
|
||
/**
|
||
* Indicates the kind of matched token, if any.
|
||
*
|
||
* This differs from `get_token_name()` in that it always
|
||
* returns a static string indicating the type, whereas
|
||
* `get_token_name()` may return values derived from the
|
||
* token itself, such as a tag name or processing
|
||
* instruction tag.
|
||
*
|
||
* Possible values:
|
||
* - `#tag` when matched on a tag.
|
||
* - `#text` when matched on a text node.
|
||
* - `#cdata-section` when matched on a CDATA node.
|
||
* - `#comment` when matched on a comment.
|
||
* - `#doctype` when matched on a DOCTYPE declaration.
|
||
* - `#presumptuous-tag` when matched on an empty tag closer.
|
||
* - `#funky-comment` when matched on a funky comment.
|
||
*
|
||
* @since 6.5.0
|
||
*
|
||
* @return string|null What kind of token is matched, or null.
|
||
*/
|
||
public function get_token_type() {
|
||
switch ( $this->parser_state ) {
|
||
case self::STATE_MATCHED_TAG:
|
||
return '#tag';
|
||
|
||
case self::STATE_DOCTYPE:
|
||
return '#doctype';
|
||
|
||
default:
|
||
return $this->get_token_name();
|
||
}
|
||
}
|
||
|
||
/**
|
||
* Returns the node name represented by the token.
|
||
*
|
||
* This matches the DOM API value `nodeName`. Some values
|
||
* are static, such as `#text` for a text node, while others
|
||
* are dynamically generated from the token itself.
|
||
*
|
||
* Dynamic names:
|
||
* - Uppercase tag name for tag matches.
|
||
* - `html` for DOCTYPE declarations.
|
||
*
|
||
* Note that if the Tag Processor is not matched on a token
|
||
* then this function will return `null`, either because it
|
||
* hasn't yet found a token or because it reached the end
|
||
* of the document without matching a token.
|
||
*
|
||
* @since 6.5.0
|
||
*
|
||
* @return string|null Name of the matched token.
|
||
*/
|
||
public function get_token_name() {
|
||
switch ( $this->parser_state ) {
|
||
case self::STATE_MATCHED_TAG:
|
||
return $this->get_tag();
|
||
|
||
case self::STATE_TEXT_NODE:
|
||
return '#text';
|
||
|
||
case self::STATE_CDATA_NODE:
|
||
return '#cdata-section';
|
||
|
||
case self::STATE_COMMENT:
|
||
return '#comment';
|
||
|
||
case self::STATE_DOCTYPE:
|
||
return 'html';
|
||
|
||
case self::STATE_PRESUMPTUOUS_TAG:
|
||
return '#presumptuous-tag';
|
||
|
||
case self::STATE_FUNKY_COMMENT:
|
||
return '#funky-comment';
|
||
}
|
||
}
|
||
|
||
/**
|
||
* Indicates what kind of comment produced the comment node.
|
||
*
|
||
* Because there are different kinds of HTML syntax which produce
|
||
* comments, the Tag Processor tracks and exposes this as a type
|
||
* for the comment. Nominally only regular HTML comments exist as
|
||
* they are commonly known, but a number of unrelated syntax errors
|
||
* also produce comments.
|
||
*
|
||
* @see self::COMMENT_AS_ABRUPTLY_CLOSED_COMMENT
|
||
* @see self::COMMENT_AS_CDATA_LOOKALIKE
|
||
* @see self::COMMENT_AS_INVALID_HTML
|
||
* @see self::COMMENT_AS_HTML_COMMENT
|
||
* @see self::COMMENT_AS_PI_NODE_LOOKALIKE
|
||
*
|
||
* @since 6.5.0
|
||
*
|
||
* @return string|null
|
||
*/
|
||
public function get_comment_type() {
|
||
if ( self::STATE_COMMENT !== $this->parser_state ) {
|
||
return null;
|
||
}
|
||
|
||
return $this->comment_type;
|
||
}
|
||
|
||
/**
|
||
* Returns the modifiable text for a matched token, or an empty string.
|
||
*
|
||
* Modifiable text is text content that may be read and changed without
|
||
* changing the HTML structure of the document around it. This includes
|
||
* the contents of `#text` nodes in the HTML as well as the inner
|
||
* contents of HTML comments, Processing Instructions, and others, even
|
||
* though these nodes aren't part of a parsed DOM tree. They also contain
|
||
* the contents of SCRIPT and STYLE tags, of TEXTAREA tags, and of any
|
||
* other section in an HTML document which cannot contain HTML markup (DATA).
|
||
*
|
||
* If a token has no modifiable text then an empty string is returned to
|
||
* avoid needless crashing or type errors. An empty string does not mean
|
||
* that a token has modifiable text, and a token with modifiable text may
|
||
* have an empty string (e.g. a comment with no contents).
|
||
*
|
||
* @since 6.5.0
|
||
*
|
||
* @return string
|
||
*/
|
||
public function get_modifiable_text() {
|
||
if ( null === $this->text_starts_at ) {
|
||
return '';
|
||
}
|
||
|
||
$text = substr( $this->html, $this->text_starts_at, $this->text_length );
|
||
|
||
// Comment data is not decoded.
|
||
if (
|
||
self::STATE_CDATA_NODE === $this->parser_state ||
|
||
self::STATE_COMMENT === $this->parser_state ||
|
||
self::STATE_DOCTYPE === $this->parser_state ||
|
||
self::STATE_FUNKY_COMMENT === $this->parser_state
|
||
) {
|
||
return $text;
|
||
}
|
||
|
||
$tag_name = $this->get_tag();
|
||
if (
|
||
// Script data is not decoded.
|
||
'SCRIPT' === $tag_name ||
|
||
|
||
// RAWTEXT data is not decoded.
|
||
'IFRAME' === $tag_name ||
|
||
'NOEMBED' === $tag_name ||
|
||
'NOFRAMES' === $tag_name ||
|
||
'STYLE' === $tag_name ||
|
||
'XMP' === $tag_name
|
||
) {
|
||
return $text;
|
||
}
|
||
|
||
$decoded = html_entity_decode( $text, ENT_QUOTES | ENT_HTML5 | ENT_SUBSTITUTE );
|
||
|
||
if ( empty( $decoded ) ) {
|
||
return '';
|
||
}
|
||
|
||
/*
|
||
* TEXTAREA skips a leading newline, but this newline may appear not only as the
|
||
* literal character `\n`, but also as a character reference, such as in the
|
||
* following markup: `<textarea>
Content</textarea>`.
|
||
*
|
||
* For these cases it's important to first decode the text content before checking
|
||
* for a leading newline and removing it.
|
||
*/
|
||
if (
|
||
self::STATE_MATCHED_TAG === $this->parser_state &&
|
||
'TEXTAREA' === $tag_name &&
|
||
strlen( $decoded ) > 0 &&
|
||
"\n" === $decoded[0]
|
||
) {
|
||
return substr( $decoded, 1 );
|
||
}
|
||
|
||
return $decoded;
|
||
}
|
||
|
||
/**
|
||
* Updates or creates a new attribute on the currently matched tag with the passed value.
|
||
*
|
||
* For boolean attributes special handling is provided:
|
||
* - When `true` is passed as the value, then only the attribute name is added to the tag.
|
||
* - When `false` is passed, the attribute gets removed if it existed before.
|
||
*
|
||
* For string attributes, the value is escaped using the `esc_attr` function.
|
||
*
|
||
* @since 6.2.0
|
||
* @since 6.2.1 Fix: Only create a single update for multiple calls with case-variant attribute names.
|
||
*
|
||
* @param string $name The attribute name to target.
|
||
* @param string|bool $value The new attribute value.
|
||
* @return bool Whether an attribute value was set.
|
||
*/
|
||
public function set_attribute( $name, $value ) {
|
||
if (
|
||
self::STATE_MATCHED_TAG !== $this->parser_state ||
|
||
$this->is_closing_tag
|
||
) {
|
||
return false;
|
||
}
|
||
|
||
/*
|
||
* WordPress rejects more characters than are strictly forbidden
|
||
* in HTML5. This is to prevent additional security risks deeper
|
||
* in the WordPress and plugin stack. Specifically the
|
||
* less-than (<) greater-than (>) and ampersand (&) aren't allowed.
|
||
*
|
||
* The use of a PCRE match enables looking for specific Unicode
|
||
* code points without writing a UTF-8 decoder. Whereas scanning
|
||
* for one-byte characters is trivial (with `strcspn`), scanning
|
||
* for the longer byte sequences would be more complicated. Given
|
||
* that this shouldn't be in the hot path for execution, it's a
|
||
* reasonable compromise in efficiency without introducing a
|
||
* noticeable impact on the overall system.
|
||
*
|
||
* @see https://html.spec.whatwg.org/#attributes-2
|
||
*
|
||
* @todo As the only regex pattern maybe we should take it out?
|
||
* Are Unicode patterns available broadly in Core?
|
||
*/
|
||
if ( preg_match(
|
||
'~[' .
|
||
// Syntax-like characters.
|
||
'"\'>&</ =' .
|
||
// Control characters.
|
||
'\x{00}-\x{1F}' .
|
||
// HTML noncharacters.
|
||
'\x{FDD0}-\x{FDEF}' .
|
||
'\x{FFFE}\x{FFFF}\x{1FFFE}\x{1FFFF}\x{2FFFE}\x{2FFFF}\x{3FFFE}\x{3FFFF}' .
|
||
'\x{4FFFE}\x{4FFFF}\x{5FFFE}\x{5FFFF}\x{6FFFE}\x{6FFFF}\x{7FFFE}\x{7FFFF}' .
|
||
'\x{8FFFE}\x{8FFFF}\x{9FFFE}\x{9FFFF}\x{AFFFE}\x{AFFFF}\x{BFFFE}\x{BFFFF}' .
|
||
'\x{CFFFE}\x{CFFFF}\x{DFFFE}\x{DFFFF}\x{EFFFE}\x{EFFFF}\x{FFFFE}\x{FFFFF}' .
|
||
'\x{10FFFE}\x{10FFFF}' .
|
||
']~Ssu',
|
||
$name
|
||
) ) {
|
||
_doing_it_wrong(
|
||
__METHOD__,
|
||
__( 'Invalid attribute name.' ),
|
||
'6.2.0'
|
||
);
|
||
|
||
return false;
|
||
}
|
||
|
||
/*
|
||
* > The values "true" and "false" are not allowed on boolean attributes.
|
||
* > To represent a false value, the attribute has to be omitted altogether.
|
||
* - HTML5 spec, https://html.spec.whatwg.org/#boolean-attributes
|
||
*/
|
||
if ( false === $value ) {
|
||
return $this->remove_attribute( $name );
|
||
}
|
||
|
||
if ( true === $value ) {
|
||
$updated_attribute = $name;
|
||
} else {
|
||
$escaped_new_value = esc_attr( $value );
|
||
$updated_attribute = "{$name}=\"{$escaped_new_value}\"";
|
||
}
|
||
|
||
/*
|
||
* > There must never be two or more attributes on
|
||
* > the same start tag whose names are an ASCII
|
||
* > case-insensitive match for each other.
|
||
* - HTML 5 spec
|
||
*
|
||
* @see https://html.spec.whatwg.org/multipage/syntax.html#attributes-2:ascii-case-insensitive
|
||
*/
|
||
$comparable_name = strtolower( $name );
|
||
|
||
if ( isset( $this->attributes[ $comparable_name ] ) ) {
|
||
/*
|
||
* Update an existing attribute.
|
||
*
|
||
* Example – set attribute id to "new" in <div id="initial_id" />:
|
||
*
|
||
* <div id="initial_id"/>
|
||
* ^-------------^
|
||
* start end
|
||
* replacement: `id="new"`
|
||
*
|
||
* Result: <div id="new"/>
|
||
*/
|
||
$existing_attribute = $this->attributes[ $comparable_name ];
|
||
$this->lexical_updates[ $comparable_name ] = new WP_HTML_Text_Replacement(
|
||
$existing_attribute->start,
|
||
$existing_attribute->length,
|
||
$updated_attribute
|
||
);
|
||
} else {
|
||
/*
|
||
* Create a new attribute at the tag's name end.
|
||
*
|
||
* Example – add attribute id="new" to <div />:
|
||
*
|
||
* <div/>
|
||
* ^
|
||
* start and end
|
||
* replacement: ` id="new"`
|
||
*
|
||
* Result: <div id="new"/>
|
||
*/
|
||
$this->lexical_updates[ $comparable_name ] = new WP_HTML_Text_Replacement(
|
||
$this->tag_name_starts_at + $this->tag_name_length,
|
||
0,
|
||
' ' . $updated_attribute
|
||
);
|
||
}
|
||
|
||
/*
|
||
* Any calls to update the `class` attribute directly should wipe out any
|
||
* enqueued class changes from `add_class` and `remove_class`.
|
||
*/
|
||
if ( 'class' === $comparable_name && ! empty( $this->classname_updates ) ) {
|
||
$this->classname_updates = array();
|
||
}
|
||
|
||
return true;
|
||
}
|
||
|
||
/**
|
||
* Remove an attribute from the currently-matched tag.
|
||
*
|
||
* @since 6.2.0
|
||
*
|
||
* @param string $name The attribute name to remove.
|
||
* @return bool Whether an attribute was removed.
|
||
*/
|
||
public function remove_attribute( $name ) {
|
||
if (
|
||
self::STATE_MATCHED_TAG !== $this->parser_state ||
|
||
$this->is_closing_tag
|
||
) {
|
||
return false;
|
||
}
|
||
|
||
/*
|
||
* > There must never be two or more attributes on
|
||
* > the same start tag whose names are an ASCII
|
||
* > case-insensitive match for each other.
|
||
* - HTML 5 spec
|
||
*
|
||
* @see https://html.spec.whatwg.org/multipage/syntax.html#attributes-2:ascii-case-insensitive
|
||
*/
|
||
$name = strtolower( $name );
|
||
|
||
/*
|
||
* Any calls to update the `class` attribute directly should wipe out any
|
||
* enqueued class changes from `add_class` and `remove_class`.
|
||
*/
|
||
if ( 'class' === $name && count( $this->classname_updates ) !== 0 ) {
|
||
$this->classname_updates = array();
|
||
}
|
||
|
||
/*
|
||
* If updating an attribute that didn't exist in the input
|
||
* document, then remove the enqueued update and move on.
|
||
*
|
||
* For example, this might occur when calling `remove_attribute()`
|
||
* after calling `set_attribute()` for the same attribute
|
||
* and when that attribute wasn't originally present.
|
||
*/
|
||
if ( ! isset( $this->attributes[ $name ] ) ) {
|
||
if ( isset( $this->lexical_updates[ $name ] ) ) {
|
||
unset( $this->lexical_updates[ $name ] );
|
||
}
|
||
return false;
|
||
}
|
||
|
||
/*
|
||
* Removes an existing tag attribute.
|
||
*
|
||
* Example – remove the attribute id from <div id="main"/>:
|
||
* <div id="initial_id"/>
|
||
* ^-------------^
|
||
* start end
|
||
* replacement: ``
|
||
*
|
||
* Result: <div />
|
||
*/
|
||
$this->lexical_updates[ $name ] = new WP_HTML_Text_Replacement(
|
||
$this->attributes[ $name ]->start,
|
||
$this->attributes[ $name ]->length,
|
||
''
|
||
);
|
||
|
||
// Removes any duplicated attributes if they were also present.
|
||
if ( null !== $this->duplicate_attributes && array_key_exists( $name, $this->duplicate_attributes ) ) {
|
||
foreach ( $this->duplicate_attributes[ $name ] as $attribute_token ) {
|
||
$this->lexical_updates[] = new WP_HTML_Text_Replacement(
|
||
$attribute_token->start,
|
||
$attribute_token->length,
|
||
''
|
||
);
|
||
}
|
||
}
|
||
|
||
return true;
|
||
}
|
||
|
||
/**
|
||
* Adds a new class name to the currently matched tag.
|
||
*
|
||
* @since 6.2.0
|
||
*
|
||
* @param string $class_name The class name to add.
|
||
* @return bool Whether the class was set to be added.
|
||
*/
|
||
public function add_class( $class_name ) {
|
||
if (
|
||
self::STATE_MATCHED_TAG !== $this->parser_state ||
|
||
$this->is_closing_tag
|
||
) {
|
||
return false;
|
||
}
|
||
|
||
$this->classname_updates[ $class_name ] = self::ADD_CLASS;
|
||
|
||
return true;
|
||
}
|
||
|
||
/**
|
||
* Removes a class name from the currently matched tag.
|
||
*
|
||
* @since 6.2.0
|
||
*
|
||
* @param string $class_name The class name to remove.
|
||
* @return bool Whether the class was set to be removed.
|
||
*/
|
||
public function remove_class( $class_name ) {
|
||
if (
|
||
self::STATE_MATCHED_TAG !== $this->parser_state ||
|
||
$this->is_closing_tag
|
||
) {
|
||
return false;
|
||
}
|
||
|
||
if ( null !== $this->tag_name_starts_at ) {
|
||
$this->classname_updates[ $class_name ] = self::REMOVE_CLASS;
|
||
}
|
||
|
||
return true;
|
||
}
|
||
|
||
/**
|
||
* Returns the string representation of the HTML Tag Processor.
|
||
*
|
||
* @since 6.2.0
|
||
*
|
||
* @see WP_HTML_Tag_Processor::get_updated_html()
|
||
*
|
||
* @return string The processed HTML.
|
||
*/
|
||
public function __toString() {
|
||
return $this->get_updated_html();
|
||
}
|
||
|
||
/**
|
||
* Returns the string representation of the HTML Tag Processor.
|
||
*
|
||
* @since 6.2.0
|
||
* @since 6.2.1 Shifts the internal cursor corresponding to the applied updates.
|
||
* @since 6.4.0 No longer calls subclass method `next_tag()` after updating HTML.
|
||
*
|
||
* @return string The processed HTML.
|
||
*/
|
||
public function get_updated_html() {
|
||
$requires_no_updating = 0 === count( $this->classname_updates ) && 0 === count( $this->lexical_updates );
|
||
|
||
/*
|
||
* When there is nothing more to update and nothing has already been
|
||
* updated, return the original document and avoid a string copy.
|
||
*/
|
||
if ( $requires_no_updating ) {
|
||
return $this->html;
|
||
}
|
||
|
||
/*
|
||
* Keep track of the position right before the current tag. This will
|
||
* be necessary for reparsing the current tag after updating the HTML.
|
||
*/
|
||
$before_current_tag = $this->token_starts_at;
|
||
|
||
/*
|
||
* 1. Apply the enqueued edits and update all the pointers to reflect those changes.
|
||
*/
|
||
$this->class_name_updates_to_attributes_updates();
|
||
$before_current_tag += $this->apply_attributes_updates( $before_current_tag );
|
||
|
||
/*
|
||
* 2. Rewind to before the current tag and reparse to get updated attributes.
|
||
*
|
||
* At this point the internal cursor points to the end of the tag name.
|
||
* Rewind before the tag name starts so that it's as if the cursor didn't
|
||
* move; a call to `next_tag()` will reparse the recently-updated attributes
|
||
* and additional calls to modify the attributes will apply at this same
|
||
* location, but in order to avoid issues with subclasses that might add
|
||
* behaviors to `next_tag()`, the internal methods should be called here
|
||
* instead.
|
||
*
|
||
* It's important to note that in this specific place there will be no change
|
||
* because the processor was already at a tag when this was called and it's
|
||
* rewinding only to the beginning of this very tag before reprocessing it
|
||
* and its attributes.
|
||
*
|
||
* <p>Previous HTML<em>More HTML</em></p>
|
||
* ↑ │ back up by the length of the tag name plus the opening <
|
||
* └←─┘ back up by strlen("em") + 1 ==> 3
|
||
*/
|
||
$this->bytes_already_parsed = $before_current_tag;
|
||
$this->parse_next_tag();
|
||
// Reparse the attributes.
|
||
while ( $this->parse_next_attribute() ) {
|
||
continue;
|
||
}
|
||
|
||
$tag_ends_at = strpos( $this->html, '>', $this->bytes_already_parsed );
|
||
$this->token_length = $tag_ends_at - $this->token_starts_at;
|
||
$this->bytes_already_parsed = $tag_ends_at;
|
||
|
||
return $this->html;
|
||
}
|
||
|
||
/**
|
||
* Parses tag query input into internal search criteria.
|
||
*
|
||
* @since 6.2.0
|
||
*
|
||
* @param array|string|null $query {
|
||
* Optional. Which tag name to find, having which class, etc. Default is to find any tag.
|
||
*
|
||
* @type string|null $tag_name Which tag to find, or `null` for "any tag."
|
||
* @type int|null $match_offset Find the Nth tag matching all search criteria.
|
||
* 1 for "first" tag, 3 for "third," etc.
|
||
* Defaults to first tag.
|
||
* @type string|null $class_name Tag must contain this class name to match.
|
||
* @type string $tag_closers "visit" or "skip": whether to stop on tag closers, e.g. </div>.
|
||
* }
|
||
*/
|
||
private function parse_query( $query ) {
|
||
if ( null !== $query && $query === $this->last_query ) {
|
||
return;
|
||
}
|
||
|
||
$this->last_query = $query;
|
||
$this->sought_tag_name = null;
|
||
$this->sought_class_name = null;
|
||
$this->sought_match_offset = 1;
|
||
$this->stop_on_tag_closers = false;
|
||
|
||
// A single string value means "find the tag of this name".
|
||
if ( is_string( $query ) ) {
|
||
$this->sought_tag_name = $query;
|
||
return;
|
||
}
|
||
|
||
// An empty query parameter applies no restrictions on the search.
|
||
if ( null === $query ) {
|
||
return;
|
||
}
|
||
|
||
// If not using the string interface, an associative array is required.
|
||
if ( ! is_array( $query ) ) {
|
||
_doing_it_wrong(
|
||
__METHOD__,
|
||
__( 'The query argument must be an array or a tag name.' ),
|
||
'6.2.0'
|
||
);
|
||
return;
|
||
}
|
||
|
||
if ( isset( $query['tag_name'] ) && is_string( $query['tag_name'] ) ) {
|
||
$this->sought_tag_name = $query['tag_name'];
|
||
}
|
||
|
||
if ( isset( $query['class_name'] ) && is_string( $query['class_name'] ) ) {
|
||
$this->sought_class_name = $query['class_name'];
|
||
}
|
||
|
||
if ( isset( $query['match_offset'] ) && is_int( $query['match_offset'] ) && 0 < $query['match_offset'] ) {
|
||
$this->sought_match_offset = $query['match_offset'];
|
||
}
|
||
|
||
if ( isset( $query['tag_closers'] ) ) {
|
||
$this->stop_on_tag_closers = 'visit' === $query['tag_closers'];
|
||
}
|
||
}
|
||
|
||
|
||
/**
|
||
* Checks whether a given tag and its attributes match the search criteria.
|
||
*
|
||
* @since 6.2.0
|
||
*
|
||
* @return bool Whether the given tag and its attribute match the search criteria.
|
||
*/
|
||
private function matches() {
|
||
if ( $this->is_closing_tag && ! $this->stop_on_tag_closers ) {
|
||
return false;
|
||
}
|
||
|
||
// Does the tag name match the requested tag name in a case-insensitive manner?
|
||
if ( null !== $this->sought_tag_name ) {
|
||
/*
|
||
* String (byte) length lookup is fast. If they aren't the
|
||
* same length then they can't be the same string values.
|
||
*/
|
||
if ( strlen( $this->sought_tag_name ) !== $this->tag_name_length ) {
|
||
return false;
|
||
}
|
||
|
||
/*
|
||
* Check each character to determine if they are the same.
|
||
* Defer calls to `strtoupper()` to avoid them when possible.
|
||
* Calling `strcasecmp()` here tested slowed than comparing each
|
||
* character, so unless benchmarks show otherwise, it should
|
||
* not be used.
|
||
*
|
||
* It's expected that most of the time that this runs, a
|
||
* lower-case tag name will be supplied and the input will
|
||
* contain lower-case tag names, thus normally bypassing
|
||
* the case comparison code.
|
||
*/
|
||
for ( $i = 0; $i < $this->tag_name_length; $i++ ) {
|
||
$html_char = $this->html[ $this->tag_name_starts_at + $i ];
|
||
$tag_char = $this->sought_tag_name[ $i ];
|
||
|
||
if ( $html_char !== $tag_char && strtoupper( $html_char ) !== $tag_char ) {
|
||
return false;
|
||
}
|
||
}
|
||
}
|
||
|
||
if ( null !== $this->sought_class_name && ! $this->has_class( $this->sought_class_name ) ) {
|
||
return false;
|
||
}
|
||
|
||
return true;
|
||
}
|
||
|
||
/**
|
||
* Parser Ready State.
|
||
*
|
||
* Indicates that the parser is ready to run and waiting for a state transition.
|
||
* It may not have started yet, or it may have just finished parsing a token and
|
||
* is ready to find the next one.
|
||
*
|
||
* @since 6.5.0
|
||
*
|
||
* @access private
|
||
*/
|
||
const STATE_READY = 'STATE_READY';
|
||
|
||
/**
|
||
* Parser Complete State.
|
||
*
|
||
* Indicates that the parser has reached the end of the document and there is
|
||
* nothing left to scan. It finished parsing the last token completely.
|
||
*
|
||
* @since 6.5.0
|
||
*
|
||
* @access private
|
||
*/
|
||
const STATE_COMPLETE = 'STATE_COMPLETE';
|
||
|
||
/**
|
||
* Parser Incomplete Input State.
|
||
*
|
||
* Indicates that the parser has reached the end of the document before finishing
|
||
* a token. It started parsing a token but there is a possibility that the input
|
||
* HTML document was truncated in the middle of a token.
|
||
*
|
||
* The parser is reset at the start of the incomplete token and has paused. There
|
||
* is nothing more than can be scanned unless provided a more complete document.
|
||
*
|
||
* @since 6.5.0
|
||
*
|
||
* @access private
|
||
*/
|
||
const STATE_INCOMPLETE_INPUT = 'STATE_INCOMPLETE_INPUT';
|
||
|
||
/**
|
||
* Parser Matched Tag State.
|
||
*
|
||
* Indicates that the parser has found an HTML tag and it's possible to get
|
||
* the tag name and read or modify its attributes (if it's not a closing tag).
|
||
*
|
||
* @since 6.5.0
|
||
*
|
||
* @access private
|
||
*/
|
||
const STATE_MATCHED_TAG = 'STATE_MATCHED_TAG';
|
||
|
||
/**
|
||
* Parser Text Node State.
|
||
*
|
||
* Indicates that the parser has found a text node and it's possible
|
||
* to read and modify that text.
|
||
*
|
||
* @since 6.5.0
|
||
*
|
||
* @access private
|
||
*/
|
||
const STATE_TEXT_NODE = 'STATE_TEXT_NODE';
|
||
|
||
/**
|
||
* Parser CDATA Node State.
|
||
*
|
||
* Indicates that the parser has found a CDATA node and it's possible
|
||
* to read and modify its modifiable text. Note that in HTML there are
|
||
* no CDATA nodes outside of foreign content (SVG and MathML). Outside
|
||
* of foreign content, they are treated as HTML comments.
|
||
*
|
||
* @since 6.5.0
|
||
*
|
||
* @access private
|
||
*/
|
||
const STATE_CDATA_NODE = 'STATE_CDATA_NODE';
|
||
|
||
/**
|
||
* Indicates that the parser has found an HTML comment and it's
|
||
* possible to read and modify its modifiable text.
|
||
*
|
||
* @since 6.5.0
|
||
*
|
||
* @access private
|
||
*/
|
||
const STATE_COMMENT = 'STATE_COMMENT';
|
||
|
||
/**
|
||
* Indicates that the parser has found a DOCTYPE node and it's
|
||
* possible to read and modify its modifiable text.
|
||
*
|
||
* @since 6.5.0
|
||
*
|
||
* @access private
|
||
*/
|
||
const STATE_DOCTYPE = 'STATE_DOCTYPE';
|
||
|
||
/**
|
||
* Indicates that the parser has found an empty tag closer `</>`.
|
||
*
|
||
* Note that in HTML there are no empty tag closers, and they
|
||
* are ignored. Nonetheless, the Tag Processor still
|
||
* recognizes them as they appear in the HTML stream.
|
||
*
|
||
* These were historically discussed as a "presumptuous tag
|
||
* closer," which would close the nearest open tag, but were
|
||
* dismissed in favor of explicitly-closing tags.
|
||
*
|
||
* @since 6.5.0
|
||
*
|
||
* @access private
|
||
*/
|
||
const STATE_PRESUMPTUOUS_TAG = 'STATE_PRESUMPTUOUS_TAG';
|
||
|
||
/**
|
||
* Indicates that the parser has found a "funky comment"
|
||
* and it's possible to read and modify its modifiable text.
|
||
*
|
||
* Example:
|
||
*
|
||
* </%url>
|
||
* </{"wp-bit":"query/post-author"}>
|
||
* </2>
|
||
*
|
||
* Funky comments are tag closers with invalid tag names. Note
|
||
* that in HTML these are turn into bogus comments. Nonetheless,
|
||
* the Tag Processor recognizes them in a stream of HTML and
|
||
* exposes them for inspection and modification.
|
||
*
|
||
* @since 6.5.0
|
||
*
|
||
* @access private
|
||
*/
|
||
const STATE_FUNKY_COMMENT = 'STATE_WP_FUNKY';
|
||
|
||
/**
|
||
* Indicates that a comment was created when encountering abruptly-closed HTML comment.
|
||
*
|
||
* Example:
|
||
*
|
||
* <!-->
|
||
* <!--->
|
||
*
|
||
* @since 6.5.0
|
||
*/
|
||
const COMMENT_AS_ABRUPTLY_CLOSED_COMMENT = 'COMMENT_AS_ABRUPTLY_CLOSED_COMMENT';
|
||
|
||
/**
|
||
* Indicates that a comment would be parsed as a CDATA node,
|
||
* were HTML to allow CDATA nodes outside of foreign content.
|
||
*
|
||
* Example:
|
||
*
|
||
* <![CDATA[This is a CDATA node.]]>
|
||
*
|
||
* This is an HTML comment, but it looks like a CDATA node.
|
||
*
|
||
* @since 6.5.0
|
||
*/
|
||
const COMMENT_AS_CDATA_LOOKALIKE = 'COMMENT_AS_CDATA_LOOKALIKE';
|
||
|
||
/**
|
||
* Indicates that a comment was created when encountering
|
||
* normative HTML comment syntax.
|
||
*
|
||
* Example:
|
||
*
|
||
* <!-- this is a comment -->
|
||
*
|
||
* @since 6.5.0
|
||
*/
|
||
const COMMENT_AS_HTML_COMMENT = 'COMMENT_AS_HTML_COMMENT';
|
||
|
||
/**
|
||
* Indicates that a comment would be parsed as a Processing
|
||
* Instruction node, were they to exist within HTML.
|
||
*
|
||
* Example:
|
||
*
|
||
* <?wp __( 'Like' ) ?>
|
||
*
|
||
* This is an HTML comment, but it looks like a CDATA node.
|
||
*
|
||
* @since 6.5.0
|
||
*/
|
||
const COMMENT_AS_PI_NODE_LOOKALIKE = 'COMMENT_AS_PI_NODE_LOOKALIKE';
|
||
|
||
/**
|
||
* Indicates that a comment was created when encountering invalid
|
||
* HTML input, a so-called "bogus comment."
|
||
*
|
||
* Example:
|
||
*
|
||
* <?nothing special>
|
||
* <!{nothing special}>
|
||
*
|
||
* @since 6.5.0
|
||
*/
|
||
const COMMENT_AS_INVALID_HTML = 'COMMENT_AS_INVALID_HTML';
|
||
}
|