| [ Index ] |
PHP Cross Reference of WordPress Trunk (Updated Daily) |
[Summary view] [Print] [Text view]
1 <?php 2 /** 3 * HTML API: WP_HTML_Tag_Processor class 4 * 5 * Scans through an HTML document to find specific tags, then 6 * transforms those tags by adding, removing, or updating the 7 * values of the HTML attributes within that tag (opener). 8 * 9 * Does not fully parse HTML or _recurse_ into the HTML structure 10 * Instead this scans linearly through a document and only parses 11 * the HTML tag openers. 12 * 13 * ### Possible future direction for this module 14 * 15 * - Prune the whitespace when removing classes/attributes: e.g. "a b c" -> "c" not " c". 16 * This would increase the size of the changes for some operations but leave more 17 * natural-looking output HTML. 18 * 19 * @package WordPress 20 * @subpackage HTML-API 21 * @since 6.2.0 22 */ 23 24 /** 25 * Core class used to modify attributes in an HTML document for tags matching a query. 26 * 27 * ## Usage 28 * 29 * Use of this class requires three steps: 30 * 31 * 1. Create a new class instance with your input HTML document. 32 * 2. Find the tag(s) you are looking for. 33 * 3. Request changes to the attributes in those tag(s). 34 * 35 * Example: 36 * 37 * $tags = new WP_HTML_Tag_Processor( $html ); 38 * if ( $tags->next_tag( 'option' ) ) { 39 * $tags->set_attribute( 'selected', true ); 40 * } 41 * 42 * ### Finding tags 43 * 44 * The `next_tag()` function moves the internal cursor through 45 * your input HTML document until it finds a tag meeting any of 46 * the supplied restrictions in the optional query argument. If 47 * no argument is provided then it will find the next HTML tag, 48 * regardless of what kind it is. 49 * 50 * If you want to _find whatever the next tag is_: 51 * 52 * $tags->next_tag(); 53 * 54 * | Goal | Query | 55 * |-----------------------------------------------------------|---------------------------------------------------------------------------------| 56 * | Find any tag. | `$tags->next_tag();` | 57 * | Find next image tag. | `$tags->next_tag( array( 'tag_name' => 'img' ) );` | 58 * | Find next image tag (without passing the array). | `$tags->next_tag( 'img' );` | 59 * | Find next tag containing the `fullwidth` CSS class. | `$tags->next_tag( array( 'class_name' => 'fullwidth' ) );` | 60 * | Find next image tag containing the `fullwidth` CSS class. | `$tags->next_tag( array( 'tag_name' => 'img', 'class_name' => 'fullwidth' ) );` | 61 * 62 * If a tag was found meeting your criteria then `next_tag()` 63 * will return `true` and you can proceed to modify it. If it 64 * returns `false`, however, it failed to find the tag and 65 * moved the cursor to the end of the file. 66 * 67 * Once the cursor reaches the end of the file the processor 68 * is done and if you want to reach an earlier tag you will 69 * need to recreate the processor and start over, as it's 70 * unable to back up or move in reverse. 71 * 72 * See the section on bookmarks for an exception to this 73 * no-backing-up rule. 74 * 75 * #### Custom queries 76 * 77 * Sometimes it's necessary to further inspect an HTML tag than 78 * the query syntax here permits. In these cases one may further 79 * inspect the search results using the read-only functions 80 * provided by the processor or external state or variables. 81 * 82 * Example: 83 * 84 * // Paint up to the first five DIV or SPAN tags marked with the "jazzy" style. 85 * $remaining_count = 5; 86 * while ( $remaining_count > 0 && $tags->next_tag() ) { 87 * if ( 88 * ( 'DIV' === $tags->get_tag() || 'SPAN' === $tags->get_tag() ) && 89 * 'jazzy' === $tags->get_attribute( 'data-style' ) 90 * ) { 91 * $tags->add_class( 'theme-style-everest-jazz' ); 92 * $remaining_count--; 93 * } 94 * } 95 * 96 * `get_attribute()` will return `null` if the attribute wasn't present 97 * on the tag when it was called. It may return `""` (the empty string) 98 * in cases where the attribute was present but its value was empty. 99 * For boolean attributes, those whose name is present but no value is 100 * given, it will return `true` (the only way to set `false` for an 101 * attribute is to remove it). 102 * 103 * #### When matching fails 104 * 105 * When `next_tag()` returns `false` it could mean different things: 106 * 107 * - The requested tag wasn't found in the input document. 108 * - The input document ended in the middle of an HTML syntax element. 109 * 110 * When a document ends in the middle of a syntax element it will pause 111 * the processor. This is to make it possible in the future to extend the 112 * input document and proceed - an important requirement for chunked 113 * streaming parsing of a document. 114 * 115 * Example: 116 * 117 * $processor = new WP_HTML_Tag_Processor( 'This <div is="a" partial="token' ); 118 * false === $processor->next_tag(); 119 * 120 * If a special element (see next section) is encountered but no closing tag 121 * is found it will count as an incomplete tag. The parser will pause as if 122 * the opening tag were incomplete. 123 * 124 * Example: 125 * 126 * $processor = new WP_HTML_Tag_Processor( '<style>// there could be more styling to come' ); 127 * false === $processor->next_tag(); 128 * 129 * $processor = new WP_HTML_Tag_Processor( '<style>// this is everything</style><div>' ); 130 * true === $processor->next_tag( 'DIV' ); 131 * 132 * #### Special self-contained elements 133 * 134 * Some HTML elements are handled in a special way; their start and end tags 135 * act like a void tag. These are special because their contents can't contain 136 * HTML markup. Everything inside these elements is handled in a special way 137 * and content that _appears_ like HTML tags inside of them isn't. There can 138 * be no nesting in these elements. 139 * 140 * In the following list, "raw text" means that all of the content in the HTML 141 * until the matching closing tag is treated verbatim without any replacements 142 * and without any parsing. 143 * 144 * - IFRAME allows no content but requires a closing tag. 145 * - NOEMBED (deprecated) content is raw text. 146 * - NOFRAMES (deprecated) content is raw text. 147 * - SCRIPT content is plaintext apart from legacy rules allowing `</script>` inside an HTML comment. 148 * - STYLE content is raw text. 149 * - TITLE content is plain text but character references are decoded. 150 * - TEXTAREA content is plain text but character references are decoded. 151 * - XMP (deprecated) content is raw text. 152 * 153 * ### Modifying HTML attributes for a found tag 154 * 155 * Once you've found the start of an opening tag you can modify 156 * any number of the attributes on that tag. You can set a new 157 * value for an attribute, remove the entire attribute, or do 158 * nothing and move on to the next opening tag. 159 * 160 * Example: 161 * 162 * if ( $tags->next_tag( array( 'class_name' => 'wp-group-block' ) ) ) { 163 * $tags->set_attribute( 'title', 'This groups the contained content.' ); 164 * $tags->remove_attribute( 'data-test-id' ); 165 * } 166 * 167 * If `set_attribute()` is called for an existing attribute it will 168 * overwrite the existing value. Similarly, calling `remove_attribute()` 169 * for a non-existing attribute has no effect on the document. Both 170 * of these methods are safe to call without knowing if a given attribute 171 * exists beforehand. 172 * 173 * ### Modifying CSS classes for a found tag 174 * 175 * The tag processor treats the `class` attribute as a special case. 176 * Because it's a common operation to add or remove CSS classes, this 177 * interface adds helper methods to make that easier. 178 * 179 * As with attribute values, adding or removing CSS classes is a safe 180 * operation that doesn't require checking if the attribute or class 181 * exists before making changes. If removing the only class then the 182 * entire `class` attribute will be removed. 183 * 184 * Example: 185 * 186 * // from `<span>Yippee!</span>` 187 * // to `<span class="is-active">Yippee!</span>` 188 * $tags->add_class( 'is-active' ); 189 * 190 * // from `<span class="excited">Yippee!</span>` 191 * // to `<span class="excited is-active">Yippee!</span>` 192 * $tags->add_class( 'is-active' ); 193 * 194 * // from `<span class="is-active heavy-accent">Yippee!</span>` 195 * // to `<span class="is-active heavy-accent">Yippee!</span>` 196 * $tags->add_class( 'is-active' ); 197 * 198 * // from `<input type="text" class="is-active rugby not-disabled" length="24">` 199 * // to `<input type="text" class="is-active not-disabled" length="24"> 200 * $tags->remove_class( 'rugby' ); 201 * 202 * // from `<input type="text" class="rugby" length="24">` 203 * // to `<input type="text" length="24"> 204 * $tags->remove_class( 'rugby' ); 205 * 206 * // from `<input type="text" length="24">` 207 * // to `<input type="text" length="24"> 208 * $tags->remove_class( 'rugby' ); 209 * 210 * When class changes are enqueued but a direct change to `class` is made via 211 * `set_attribute` then the changes to `set_attribute` (or `remove_attribute`) 212 * will take precedence over those made through `add_class` and `remove_class`. 213 * 214 * ### Bookmarks 215 * 216 * While scanning through the input HTMl document it's possible to set 217 * a named bookmark when a particular tag is found. Later on, after 218 * continuing to scan other tags, it's possible to `seek` to one of 219 * the set bookmarks and then proceed again from that point forward. 220 * 221 * Because bookmarks create processing overhead one should avoid 222 * creating too many of them. As a rule, create only bookmarks 223 * of known string literal names; avoid creating "mark_{$index}" 224 * and so on. It's fine from a performance standpoint to create a 225 * bookmark and update it frequently, such as within a loop. 226 * 227 * $total_todos = 0; 228 * while ( $p->next_tag( array( 'tag_name' => 'UL', 'class_name' => 'todo' ) ) ) { 229 * $p->set_bookmark( 'list-start' ); 230 * while ( $p->next_tag( array( 'tag_closers' => 'visit' ) ) ) { 231 * if ( 'UL' === $p->get_tag() && $p->is_tag_closer() ) { 232 * $p->set_bookmark( 'list-end' ); 233 * $p->seek( 'list-start' ); 234 * $p->set_attribute( 'data-contained-todos', (string) $total_todos ); 235 * $total_todos = 0; 236 * $p->seek( 'list-end' ); 237 * break; 238 * } 239 * 240 * if ( 'LI' === $p->get_tag() && ! $p->is_tag_closer() ) { 241 * $total_todos++; 242 * } 243 * } 244 * } 245 * 246 * ## Tokens and finer-grained processing. 247 * 248 * It's possible to scan through every lexical token in the 249 * HTML document using the `next_token()` function. This 250 * alternative form takes no argument and provides no built-in 251 * query syntax. 252 * 253 * Example: 254 * 255 * $title = '(untitled)'; 256 * $text = ''; 257 * while ( $processor->next_token() ) { 258 * switch ( $processor->get_token_name() ) { 259 * case '#text': 260 * $text .= $processor->get_modifiable_text(); 261 * break; 262 * 263 * case 'BR': 264 * $text .= "\n"; 265 * break; 266 * 267 * case 'TITLE': 268 * $title = $processor->get_modifiable_text(); 269 * break; 270 * } 271 * } 272 * return trim( "# {$title}\n\n{$text}" ); 273 * 274 * ### Tokens and _modifiable text_. 275 * 276 * #### Special "atomic" HTML elements. 277 * 278 * Not all HTML elements are able to contain other elements inside of them. 279 * For instance, the contents inside a TITLE element are plaintext (except 280 * that character references like & will be decoded). This means that 281 * if the string `<img>` appears inside a TITLE element, then it's not an 282 * image tag, but rather it's text describing an image tag. Likewise, the 283 * contents of a SCRIPT or STYLE element are handled entirely separately in 284 * a browser than the contents of other elements because they represent a 285 * different language than HTML. 286 * 287 * For these elements the Tag Processor treats the entire sequence as one, 288 * from the opening tag, including its contents, through its closing tag. 289 * This means that the it's not possible to match the closing tag for a 290 * SCRIPT element unless it's unexpected; the Tag Processor already matched 291 * it when it found the opening tag. 292 * 293 * The inner contents of these elements are that element's _modifiable text_. 294 * 295 * The special elements are: 296 * - `SCRIPT` whose contents are treated as raw plaintext but supports a legacy 297 * style of including JavaScript inside of HTML comments to avoid accidentally 298 * closing the SCRIPT from inside a JavaScript string. E.g. `console.log( '</script>' )`. 299 * - `TITLE` and `TEXTAREA` whose contents are treated as plaintext and then any 300 * character references are decoded. E.g. `1 < 2 < 3` becomes `1 < 2 < 3`. 301 * - `IFRAME`, `NOSCRIPT`, `NOEMBED`, `NOFRAME`, `STYLE` whose contents are treated as 302 * raw plaintext and left as-is. E.g. `1 < 2 < 3` remains `1 < 2 < 3`. 303 * 304 * #### Other tokens with modifiable text. 305 * 306 * There are also non-elements which are void/self-closing in nature and contain 307 * modifiable text that is part of that individual syntax token itself. 308 * 309 * - `#text` nodes, whose entire token _is_ the modifiable text. 310 * - HTML comments and tokens that become comments due to some syntax error. The 311 * text for these tokens is the portion of the comment inside of the syntax. 312 * E.g. for `<!-- comment -->` the text is `" comment "` (note the spaces are included). 313 * - `CDATA` sections, whose text is the content inside of the section itself. E.g. for 314 * `<![CDATA[some content]]>` the text is `"some content"` (with restrictions [1]). 315 * - "Funky comments," which are a special case of invalid closing tags whose name is 316 * invalid. The text for these nodes is the text that a browser would transform into 317 * an HTML comment when parsing. E.g. for `</%post_author>` the text is `%post_author`. 318 * - `DOCTYPE` declarations like `<DOCTYPE html>` which have no closing tag. 319 * - XML Processing instruction nodes like `<?wp __( "Like" ); ?>` (with restrictions [2]). 320 * - The empty end tag `</>` which is ignored in the browser and DOM. 321 * 322 * [1]: There are no CDATA sections in HTML. When encountering `<![CDATA[`, everything 323 * until the next `>` becomes a bogus HTML comment, meaning there can be no CDATA 324 * section in an HTML document containing `>`. The Tag Processor will first find 325 * all valid and bogus HTML comments, and then if the comment _would_ have been a 326 * CDATA section _were they to exist_, it will indicate this as the type of comment. 327 * 328 * [2]: XML allows a broader range of characters in a processing instruction's target name 329 * and disallows "xml" as a name, since it's special. The Tag Processor only recognizes 330 * target names with an ASCII-representable subset of characters. It also exhibits the 331 * same constraint as with CDATA sections, in that `>` cannot exist within the token 332 * since Processing Instructions do no exist within HTML and their syntax transforms 333 * into a bogus comment in the DOM. 334 * 335 * ## Design and limitations 336 * 337 * The Tag Processor is designed to linearly scan HTML documents and tokenize 338 * HTML tags and their attributes. It's designed to do this as efficiently as 339 * possible without compromising parsing integrity. Therefore it will be 340 * slower than some methods of modifying HTML, such as those incorporating 341 * over-simplified PCRE patterns, but will not introduce the defects and 342 * failures that those methods bring in, which lead to broken page renders 343 * and often to security vulnerabilities. On the other hand, it will be faster 344 * than full-blown HTML parsers such as DOMDocument and use considerably 345 * less memory. It requires a negligible memory overhead, enough to consider 346 * it a zero-overhead system. 347 * 348 * The performance characteristics are maintained by avoiding tree construction 349 * and semantic cleanups which are specified in HTML5. Because of this, for 350 * example, it's not possible for the Tag Processor to associate any given 351 * opening tag with its corresponding closing tag, or to return the inner markup 352 * inside an element. Systems may be built on top of the Tag Processor to do 353 * this, but the Tag Processor is and should be constrained so it can remain an 354 * efficient, low-level, and reliable HTML scanner. 355 * 356 * The Tag Processor's design incorporates a "garbage-in-garbage-out" philosophy. 357 * HTML5 specifies that certain invalid content be transformed into different forms 358 * for display, such as removing null bytes from an input document and replacing 359 * invalid characters with the Unicode replacement character `U+FFFD` (visually "�"). 360 * Where errors or transformations exist within the HTML5 specification, the Tag Processor 361 * leaves those invalid inputs untouched, passing them through to the final browser 362 * to handle. While this implies that certain operations will be non-spec-compliant, 363 * such as reading the value of an attribute with invalid content, it also preserves a 364 * simplicity and efficiency for handling those error cases. 365 * 366 * Most operations within the Tag Processor are designed to minimize the difference 367 * between an input and output document for any given change. For example, the 368 * `add_class` and `remove_class` methods preserve whitespace and the class ordering 369 * within the `class` attribute; and when encountering tags with duplicated attributes, 370 * the Tag Processor will leave those invalid duplicate attributes where they are but 371 * update the proper attribute which the browser will read for parsing its value. An 372 * exception to this rule is that all attribute updates store their values as 373 * double-quoted strings, meaning that attributes on input with single-quoted or 374 * unquoted values will appear in the output with double-quotes. 375 * 376 * ### Scripting Flag 377 * 378 * The Tag Processor parses HTML with the "scripting flag" disabled. This means 379 * that it doesn't run any scripts while parsing the page. In a browser with 380 * JavaScript enabled, for example, the script can change the parse of the 381 * document as it loads. On the server, however, evaluating JavaScript is not 382 * only impractical, but also unwanted. 383 * 384 * Practically this means that the Tag Processor will descend into NOSCRIPT 385 * elements and process its child tags. Were the scripting flag enabled, such 386 * as in a typical browser, the contents of NOSCRIPT are skipped entirely. 387 * 388 * This allows the HTML API to process the content that will be presented in 389 * a browser when scripting is disabled, but it offers a different view of a 390 * page than most browser sessions will experience. E.g. the tags inside the 391 * NOSCRIPT disappear. 392 * 393 * ### Text Encoding 394 * 395 * The Tag Processor assumes that the input HTML document is encoded with a 396 * text encoding compatible with 7-bit ASCII's '<', '>', '&', ';', '/', '=', 397 * "'", '"', 'a' - 'z', 'A' - 'Z', and the whitespace characters ' ', tab, 398 * carriage-return, newline, and form-feed. 399 * 400 * In practice, this includes almost every single-byte encoding as well as 401 * UTF-8. Notably, however, it does not include UTF-16. If providing input 402 * that's incompatible, then convert the encoding beforehand. 403 * 404 * @since 6.2.0 405 * @since 6.2.1 Fix: Support for various invalid comments; attribute updates are case-insensitive. 406 * @since 6.3.2 Fix: Skip HTML-like content inside rawtext elements such as STYLE. 407 * @since 6.5.0 Pauses processor when input ends in an incomplete syntax token. 408 * Introduces "special" elements which act like void elements, e.g. TITLE, STYLE. 409 * Allows scanning through all tokens and processing modifiable text, where applicable. 410 */ 411 class WP_HTML_Tag_Processor { 412 /** 413 * The maximum number of bookmarks allowed to exist at 414 * any given time. 415 * 416 * @since 6.2.0 417 * @var int 418 * 419 * @see WP_HTML_Tag_Processor::set_bookmark() 420 */ 421 const MAX_BOOKMARKS = 10; 422 423 /** 424 * Maximum number of times seek() can be called. 425 * Prevents accidental infinite loops. 426 * 427 * @since 6.2.0 428 * @var int 429 * 430 * @see WP_HTML_Tag_Processor::seek() 431 */ 432 const MAX_SEEK_OPS = 1000; 433 434 /** 435 * The HTML document to parse. 436 * 437 * @since 6.2.0 438 * @var string 439 */ 440 protected $html; 441 442 /** 443 * The last query passed to next_tag(). 444 * 445 * @since 6.2.0 446 * @var array|null 447 */ 448 private $last_query; 449 450 /** 451 * The tag name this processor currently scans for. 452 * 453 * @since 6.2.0 454 * @var string|null 455 */ 456 private $sought_tag_name; 457 458 /** 459 * The CSS class name this processor currently scans for. 460 * 461 * @since 6.2.0 462 * @var string|null 463 */ 464 private $sought_class_name; 465 466 /** 467 * The match offset this processor currently scans for. 468 * 469 * @since 6.2.0 470 * @var int|null 471 */ 472 private $sought_match_offset; 473 474 /** 475 * Whether to visit tag closers, e.g. </div>, when walking an input document. 476 * 477 * @since 6.2.0 478 * @var bool 479 */ 480 private $stop_on_tag_closers; 481 482 /** 483 * Specifies mode of operation of the parser at any given time. 484 * 485 * | State | Meaning | 486 * | ----------------|----------------------------------------------------------------------| 487 * | *Ready* | The parser is ready to run. | 488 * | *Complete* | There is nothing left to parse. | 489 * | *Incomplete* | The HTML ended in the middle of a token; nothing more can be parsed. | 490 * | *Matched tag* | Found an HTML tag; it's possible to modify its attributes. | 491 * | *Text node* | Found a #text node; this is plaintext and modifiable. | 492 * | *CDATA node* | Found a CDATA section; this is modifiable. | 493 * | *Comment* | Found a comment or bogus comment; this is modifiable. | 494 * | *Presumptuous* | Found an empty tag closer: `</>`. | 495 * | *Funky comment* | Found a tag closer with an invalid tag name; this is modifiable. | 496 * 497 * @since 6.5.0 498 * 499 * @see WP_HTML_Tag_Processor::STATE_READY 500 * @see WP_HTML_Tag_Processor::STATE_COMPLETE 501 * @see WP_HTML_Tag_Processor::STATE_INCOMPLETE_INPUT 502 * @see WP_HTML_Tag_Processor::STATE_MATCHED_TAG 503 * @see WP_HTML_Tag_Processor::STATE_TEXT_NODE 504 * @see WP_HTML_Tag_Processor::STATE_CDATA_NODE 505 * @see WP_HTML_Tag_Processor::STATE_COMMENT 506 * @see WP_HTML_Tag_Processor::STATE_DOCTYPE 507 * @see WP_HTML_Tag_Processor::STATE_PRESUMPTUOUS_TAG 508 * @see WP_HTML_Tag_Processor::STATE_FUNKY_COMMENT 509 * 510 * @var string 511 */ 512 protected $parser_state = self::STATE_READY; 513 514 /** 515 * Indicates if the document is in quirks mode or no-quirks mode. 516 * 517 * Impact on HTML parsing: 518 * 519 * - In `NO_QUIRKS_MODE` (also known as "standard mode"): 520 * - CSS class and ID selectors match byte-for-byte (case-sensitively). 521 * - A TABLE start tag `<table>` implicitly closes any open `P` element. 522 * 523 * - In `QUIRKS_MODE`: 524 * - CSS class and ID selectors match match in an ASCII case-insensitive manner. 525 * - A TABLE start tag `<table>` opens a `TABLE` element as a child of a `P` 526 * element if one is open. 527 * 528 * Quirks and no-quirks mode are thus mostly about styling, but have an impact when 529 * tables are found inside paragraph elements. 530 * 531 * @see self::QUIRKS_MODE 532 * @see self::NO_QUIRKS_MODE 533 * 534 * @since 6.7.0 535 * 536 * @var string 537 */ 538 protected $compat_mode = self::NO_QUIRKS_MODE; 539 540 /** 541 * Indicates whether the parser is inside foreign content, 542 * e.g. inside an SVG or MathML element. 543 * 544 * One of 'html', 'svg', or 'math'. 545 * 546 * Several parsing rules change based on whether the parser 547 * is inside foreign content, including whether CDATA sections 548 * are allowed and whether a self-closing flag indicates that 549 * an element has no content. 550 * 551 * @since 6.7.0 552 * 553 * @var string 554 */ 555 private $parsing_namespace = 'html'; 556 557 /** 558 * What kind of syntax token became an HTML comment. 559 * 560 * Since there are many ways in which HTML syntax can create an HTML comment, 561 * this indicates which of those caused it. This allows the Tag Processor to 562 * represent more from the original input document than would appear in the DOM. 563 * 564 * @since 6.5.0 565 * 566 * @var string|null 567 */ 568 protected $comment_type = null; 569 570 /** 571 * What kind of text the matched text node represents, if it was subdivided. 572 * 573 * @see self::TEXT_IS_NULL_SEQUENCE 574 * @see self::TEXT_IS_WHITESPACE 575 * @see self::TEXT_IS_GENERIC 576 * @see self::subdivide_text_appropriately 577 * 578 * @since 6.7.0 579 * 580 * @var string 581 */ 582 protected $text_node_classification = self::TEXT_IS_GENERIC; 583 584 /** 585 * How many bytes from the original HTML document have been read and parsed. 586 * 587 * This value points to the latest byte offset in the input document which 588 * has been already parsed. It is the internal cursor for the Tag Processor 589 * and updates while scanning through the HTML tokens. 590 * 591 * @since 6.2.0 592 * @var int 593 */ 594 private $bytes_already_parsed = 0; 595 596 /** 597 * Byte offset in input document where current token starts. 598 * 599 * Example: 600 * 601 * <div id="test">... 602 * 01234 603 * - token starts at 0 604 * 605 * @since 6.5.0 606 * 607 * @var int|null 608 */ 609 private $token_starts_at; 610 611 /** 612 * Byte length of current token. 613 * 614 * Example: 615 * 616 * <div id="test">... 617 * 012345678901234 618 * - token length is 14 - 0 = 14 619 * 620 * a <!-- comment --> is a token. 621 * 0123456789 123456789 123456789 622 * - token length is 17 - 2 = 15 623 * 624 * @since 6.5.0 625 * 626 * @var int|null 627 */ 628 private $token_length; 629 630 /** 631 * Byte offset in input document where current tag name starts. 632 * 633 * Example: 634 * 635 * <div id="test">... 636 * 01234 637 * - tag name starts at 1 638 * 639 * @since 6.2.0 640 * 641 * @var int|null 642 */ 643 private $tag_name_starts_at; 644 645 /** 646 * Byte length of current tag name. 647 * 648 * Example: 649 * 650 * <div id="test">... 651 * 01234 652 * --- tag name length is 3 653 * 654 * @since 6.2.0 655 * 656 * @var int|null 657 */ 658 private $tag_name_length; 659 660 /** 661 * Byte offset into input document where current modifiable text starts. 662 * 663 * @since 6.5.0 664 * 665 * @var int 666 */ 667 private $text_starts_at; 668 669 /** 670 * Byte length of modifiable text. 671 * 672 * @since 6.5.0 673 * 674 * @var int 675 */ 676 private $text_length; 677 678 /** 679 * Whether the current tag is an opening tag, e.g. <div>, or a closing tag, e.g. </div>. 680 * 681 * @var bool 682 */ 683 private $is_closing_tag; 684 685 /** 686 * Lazily-built index of attributes found within an HTML tag, keyed by the attribute name. 687 * 688 * Example: 689 * 690 * // Supposing the parser is working through this content 691 * // and stops after recognizing the `id` attribute. 692 * // <div id="test-4" class=outline title="data:text/plain;base64=asdk3nk1j3fo8"> 693 * // ^ parsing will continue from this point. 694 * $this->attributes = array( 695 * 'id' => new WP_HTML_Attribute_Token( 'id', 9, 6, 5, 11, false ) 696 * ); 697 * 698 * // When picking up parsing again, or when asking to find the 699 * // `class` attribute we will continue and add to this array. 700 * $this->attributes = array( 701 * 'id' => new WP_HTML_Attribute_Token( 'id', 9, 6, 5, 11, false ), 702 * 'class' => new WP_HTML_Attribute_Token( 'class', 23, 7, 17, 13, false ) 703 * ); 704 * 705 * // Note that only the `class` attribute value is stored in the index. 706 * // That's because it is the only value used by this class at the moment. 707 * 708 * @since 6.2.0 709 * @var WP_HTML_Attribute_Token[] 710 */ 711 private $attributes = array(); 712 713 /** 714 * Tracks spans of duplicate attributes on a given tag, used for removing 715 * all copies of an attribute when calling `remove_attribute()`. 716 * 717 * @since 6.3.2 718 * 719 * @var (WP_HTML_Span[])[]|null 720 */ 721 private $duplicate_attributes = null; 722 723 /** 724 * Which class names to add or remove from a tag. 725 * 726 * These are tracked separately from attribute updates because they are 727 * semantically distinct, whereas this interface exists for the common 728 * case of adding and removing class names while other attributes are 729 * generally modified as with DOM `setAttribute` calls. 730 * 731 * When modifying an HTML document these will eventually be collapsed 732 * into a single `set_attribute( 'class', $changes )` call. 733 * 734 * Example: 735 * 736 * // Add the `wp-block-group` class, remove the `wp-group` class. 737 * $classname_updates = array( 738 * // Indexed by a comparable class name. 739 * 'wp-block-group' => WP_HTML_Tag_Processor::ADD_CLASS, 740 * 'wp-group' => WP_HTML_Tag_Processor::REMOVE_CLASS 741 * ); 742 * 743 * @since 6.2.0 744 * @var bool[] 745 */ 746 private $classname_updates = array(); 747 748 /** 749 * Tracks a semantic location in the original HTML which 750 * shifts with updates as they are applied to the document. 751 * 752 * @since 6.2.0 753 * @var WP_HTML_Span[] 754 */ 755 protected $bookmarks = array(); 756 757 const ADD_CLASS = true; 758 const REMOVE_CLASS = false; 759 const SKIP_CLASS = null; 760 761 /** 762 * Lexical replacements to apply to input HTML document. 763 * 764 * "Lexical" in this class refers to the part of this class which 765 * operates on pure text _as text_ and not as HTML. There's a line 766 * between the public interface, with HTML-semantic methods like 767 * `set_attribute` and `add_class`, and an internal state that tracks 768 * text offsets in the input document. 769 * 770 * When higher-level HTML methods are called, those have to transform their 771 * operations (such as setting an attribute's value) into text diffing 772 * operations (such as replacing the sub-string from indices A to B with 773 * some given new string). These text-diffing operations are the lexical 774 * updates. 775 * 776 * As new higher-level methods are added they need to collapse their 777 * operations into these lower-level lexical updates since that's the 778 * Tag Processor's internal language of change. Any code which creates 779 * these lexical updates must ensure that they do not cross HTML syntax 780 * boundaries, however, so these should never be exposed outside of this 781 * class or any classes which intentionally expand its functionality. 782 * 783 * These are enqueued while editing the document instead of being immediately 784 * applied to avoid processing overhead, string allocations, and string 785 * copies when applying many updates to a single document. 786 * 787 * Example: 788 * 789 * // Replace an attribute stored with a new value, indices 790 * // sourced from the lazily-parsed HTML recognizer. 791 * $start = $attributes['src']->start; 792 * $length = $attributes['src']->length; 793 * $modifications[] = new WP_HTML_Text_Replacement( $start, $length, $new_value ); 794 * 795 * // Correspondingly, something like this will appear in this array. 796 * $lexical_updates = array( 797 * WP_HTML_Text_Replacement( 14, 28, 'https://my-site.my-domain/wp-content/uploads/2014/08/kittens.jpg' ) 798 * ); 799 * 800 * @since 6.2.0 801 * @var WP_HTML_Text_Replacement[] 802 */ 803 protected $lexical_updates = array(); 804 805 /** 806 * Tracks and limits `seek()` calls to prevent accidental infinite loops. 807 * 808 * @since 6.2.0 809 * @var int 810 * 811 * @see WP_HTML_Tag_Processor::seek() 812 */ 813 protected $seek_count = 0; 814 815 /** 816 * Whether the parser should skip over an immediately-following linefeed 817 * character, as is the case with LISTING, PRE, and TEXTAREA. 818 * 819 * > If the next token is a U+000A LINE FEED (LF) character token, then 820 * > ignore that token and move on to the next one. (Newlines at the start 821 * > of [these] elements are ignored as an authoring convenience.) 822 * 823 * @since 6.7.0 824 * 825 * @var int|null 826 */ 827 private $skip_newline_at = null; 828 829 /** 830 * Constructor. 831 * 832 * @since 6.2.0 833 * 834 * @param string $html HTML to process. 835 */ 836 public function __construct( $html ) { 837 $this->html = $html; 838 } 839 840 /** 841 * Switches parsing mode into a new namespace, such as when 842 * encountering an SVG tag and entering foreign content. 843 * 844 * @since 6.7.0 845 * 846 * @param string $new_namespace One of 'html', 'svg', or 'math' indicating into what 847 * namespace the next tokens will be processed. 848 * @return bool Whether the namespace was valid and changed. 849 */ 850 public function change_parsing_namespace( string $new_namespace ): bool { 851 if ( ! in_array( $new_namespace, array( 'html', 'math', 'svg' ), true ) ) { 852 return false; 853 } 854 855 $this->parsing_namespace = $new_namespace; 856 return true; 857 } 858 859 /** 860 * Finds the next tag matching the $query. 861 * 862 * @since 6.2.0 863 * @since 6.5.0 No longer processes incomplete tokens at end of document; pauses the processor at start of token. 864 * 865 * @param array|string|null $query { 866 * Optional. Which tag name to find, having which class, etc. Default is to find any tag. 867 * 868 * @type string|null $tag_name Which tag to find, or `null` for "any tag." 869 * @type int|null $match_offset Find the Nth tag matching all search criteria. 870 * 1 for "first" tag, 3 for "third," etc. 871 * Defaults to first tag. 872 * @type string|null $class_name Tag must contain this whole class name to match. 873 * @type string|null $tag_closers "visit" or "skip": whether to stop on tag closers, e.g. </div>. 874 * } 875 * @return bool Whether a tag was matched. 876 */ 877 public function next_tag( $query = null ): bool { 878 $this->parse_query( $query ); 879 $already_found = 0; 880 881 do { 882 if ( false === $this->next_token() ) { 883 return false; 884 } 885 886 if ( self::STATE_MATCHED_TAG !== $this->parser_state ) { 887 continue; 888 } 889 890 if ( $this->matches() ) { 891 ++$already_found; 892 } 893 } while ( $already_found < $this->sought_match_offset ); 894 895 return true; 896 } 897 898 /** 899 * Finds the next token in the HTML document. 900 * 901 * An HTML document can be viewed as a stream of tokens, 902 * where tokens are things like HTML tags, HTML comments, 903 * text nodes, etc. This method finds the next token in 904 * the HTML document and returns whether it found one. 905 * 906 * If it starts parsing a token and reaches the end of the 907 * document then it will seek to the start of the last 908 * token and pause, returning `false` to indicate that it 909 * failed to find a complete token. 910 * 911 * Possible token types, based on the HTML specification: 912 * 913 * - an HTML tag, whether opening, closing, or void. 914 * - a text node - the plaintext inside tags. 915 * - an HTML comment. 916 * - a DOCTYPE declaration. 917 * - a processing instruction, e.g. `<?xml version="1.0" ?>`. 918 * 919 * The Tag Processor currently only supports the tag token. 920 * 921 * @since 6.5.0 922 * @since 6.7.0 Recognizes CDATA sections within foreign content. 923 * 924 * @return bool Whether a token was parsed. 925 */ 926 public function next_token(): bool { 927 return $this->base_class_next_token(); 928 } 929 930 /** 931 * Internal method which finds the next token in the HTML document. 932 * 933 * This method is a protected internal function which implements the logic for 934 * finding the next token in a document. It exists so that the parser can update 935 * its state without affecting the location of the cursor in the document and 936 * without triggering subclass methods for things like `next_token()`, e.g. when 937 * applying patches before searching for the next token. 938 * 939 * @since 6.5.0 940 * 941 * @access private 942 * 943 * @return bool Whether a token was parsed. 944 */ 945 private function base_class_next_token(): bool { 946 $was_at = $this->bytes_already_parsed; 947 $this->after_tag(); 948 949 // Don't proceed if there's nothing more to scan. 950 if ( 951 self::STATE_COMPLETE === $this->parser_state || 952 self::STATE_INCOMPLETE_INPUT === $this->parser_state 953 ) { 954 return false; 955 } 956 957 /* 958 * The next step in the parsing loop determines the parsing state; 959 * clear it so that state doesn't linger from the previous step. 960 */ 961 $this->parser_state = self::STATE_READY; 962 963 if ( $this->bytes_already_parsed >= strlen( $this->html ) ) { 964 $this->parser_state = self::STATE_COMPLETE; 965 return false; 966 } 967 968 // Find the next tag if it exists. 969 if ( false === $this->parse_next_tag() ) { 970 if ( self::STATE_INCOMPLETE_INPUT === $this->parser_state ) { 971 $this->bytes_already_parsed = $was_at; 972 } 973 974 return false; 975 } 976 977 /* 978 * For legacy reasons the rest of this function handles tags and their 979 * attributes. If the processor has reached the end of the document 980 * or if it matched any other token then it should return here to avoid 981 * attempting to process tag-specific syntax. 982 */ 983 if ( 984 self::STATE_INCOMPLETE_INPUT !== $this->parser_state && 985 self::STATE_COMPLETE !== $this->parser_state && 986 self::STATE_MATCHED_TAG !== $this->parser_state 987 ) { 988 return true; 989 } 990 991 // Parse all of its attributes. 992 while ( $this->parse_next_attribute() ) { 993 continue; 994 } 995 996 // Ensure that the tag closes before the end of the document. 997 if ( 998 self::STATE_INCOMPLETE_INPUT === $this->parser_state || 999 $this->bytes_already_parsed >= strlen( $this->html ) 1000 ) { 1001 // Does this appropriately clear state (parsed attributes)? 1002 $this->parser_state = self::STATE_INCOMPLETE_INPUT; 1003 $this->bytes_already_parsed = $was_at; 1004 1005 return false; 1006 } 1007 1008 $tag_ends_at = strpos( $this->html, '>', $this->bytes_already_parsed ); 1009 if ( false === $tag_ends_at ) { 1010 $this->parser_state = self::STATE_INCOMPLETE_INPUT; 1011 $this->bytes_already_parsed = $was_at; 1012 1013 return false; 1014 } 1015 $this->parser_state = self::STATE_MATCHED_TAG; 1016 $this->bytes_already_parsed = $tag_ends_at + 1; 1017 $this->token_length = $this->bytes_already_parsed - $this->token_starts_at; 1018 1019 /* 1020 * Certain tags require additional processing. The first-letter pre-check 1021 * avoids unnecessary string allocation when comparing the tag names. 1022 * 1023 * - IFRAME 1024 * - LISTING (deprecated) 1025 * - NOEMBED (deprecated) 1026 * - NOFRAMES (deprecated) 1027 * - PRE 1028 * - SCRIPT 1029 * - STYLE 1030 * - TEXTAREA 1031 * - TITLE 1032 * - XMP (deprecated) 1033 */ 1034 if ( 1035 $this->is_closing_tag || 1036 'html' !== $this->parsing_namespace || 1037 1 !== strspn( $this->html, 'iIlLnNpPsStTxX', $this->tag_name_starts_at, 1 ) 1038 ) { 1039 return true; 1040 } 1041 1042 $tag_name = $this->get_tag(); 1043 1044 /* 1045 * For LISTING, PRE, and TEXTAREA, the first linefeed of an immediately-following 1046 * text node is ignored as an authoring convenience. 1047 * 1048 * @see static::skip_newline_at 1049 */ 1050 if ( 'LISTING' === $tag_name || 'PRE' === $tag_name ) { 1051 $this->skip_newline_at = $this->bytes_already_parsed; 1052 return true; 1053 } 1054 1055 /* 1056 * There are certain elements whose children are not DATA but are instead 1057 * RCDATA or RAWTEXT. These cannot contain other elements, and the contents 1058 * are parsed as plaintext, with character references decoded in RCDATA but 1059 * not in RAWTEXT. 1060 * 1061 * These elements are described here as "self-contained" or special atomic 1062 * elements whose end tag is consumed with the opening tag, and they will 1063 * contain modifiable text inside of them. 1064 * 1065 * Preserve the opening tag pointers, as these will be overwritten 1066 * when finding the closing tag. They will be reset after finding 1067 * the closing to tag to point to the opening of the special atomic 1068 * tag sequence. 1069 */ 1070 $tag_name_starts_at = $this->tag_name_starts_at; 1071 $tag_name_length = $this->tag_name_length; 1072 $tag_ends_at = $this->token_starts_at + $this->token_length; 1073 $attributes = $this->attributes; 1074 $duplicate_attributes = $this->duplicate_attributes; 1075 1076 // Find the closing tag if necessary. 1077 switch ( $tag_name ) { 1078 case 'SCRIPT': 1079 $found_closer = $this->skip_script_data(); 1080 break; 1081 1082 case 'TEXTAREA': 1083 case 'TITLE': 1084 $found_closer = $this->skip_rcdata( $tag_name ); 1085 break; 1086 1087 /* 1088 * In the browser this list would include the NOSCRIPT element, 1089 * but the Tag Processor is an environment with the scripting 1090 * flag disabled, meaning that it needs to descend into the 1091 * NOSCRIPT element to be able to properly process what will be 1092 * sent to a browser. 1093 * 1094 * Note that this rule makes HTML5 syntax incompatible with XML, 1095 * because the parsing of this token depends on client application. 1096 * The NOSCRIPT element cannot be represented in the XHTML syntax. 1097 */ 1098 case 'IFRAME': 1099 case 'NOEMBED': 1100 case 'NOFRAMES': 1101 case 'STYLE': 1102 case 'XMP': 1103 $found_closer = $this->skip_rawtext( $tag_name ); 1104 break; 1105 1106 // No other tags should be treated in their entirety here. 1107 default: 1108 return true; 1109 } 1110 1111 if ( ! $found_closer ) { 1112 $this->parser_state = self::STATE_INCOMPLETE_INPUT; 1113 $this->bytes_already_parsed = $was_at; 1114 return false; 1115 } 1116 1117 /* 1118 * The values here look like they reference the opening tag but they reference 1119 * the closing tag instead. This is why the opening tag values were stored 1120 * above in a variable. It reads confusingly here, but that's because the 1121 * functions that skip the contents have moved all the internal cursors past 1122 * the inner content of the tag. 1123 */ 1124 $this->token_starts_at = $was_at; 1125 $this->token_length = $this->bytes_already_parsed - $this->token_starts_at; 1126 $this->text_starts_at = $tag_ends_at; 1127 $this->text_length = $this->tag_name_starts_at - $this->text_starts_at; 1128 $this->tag_name_starts_at = $tag_name_starts_at; 1129 $this->tag_name_length = $tag_name_length; 1130 $this->attributes = $attributes; 1131 $this->duplicate_attributes = $duplicate_attributes; 1132 1133 return true; 1134 } 1135 1136 /** 1137 * Whether the processor paused because the input HTML document ended 1138 * in the middle of a syntax element, such as in the middle of a tag. 1139 * 1140 * Example: 1141 * 1142 * $processor = new WP_HTML_Tag_Processor( '<input type="text" value="Th' ); 1143 * false === $processor->get_next_tag(); 1144 * true === $processor->paused_at_incomplete_token(); 1145 * 1146 * @since 6.5.0 1147 * 1148 * @return bool Whether the parse paused at the start of an incomplete token. 1149 */ 1150 public function paused_at_incomplete_token(): bool { 1151 return self::STATE_INCOMPLETE_INPUT === $this->parser_state; 1152 } 1153 1154 /** 1155 * Generator for a foreach loop to step through each class name for the matched tag. 1156 * 1157 * This generator function is designed to be used inside a "foreach" loop. 1158 * 1159 * Example: 1160 * 1161 * $p = new WP_HTML_Tag_Processor( "<div class='free <egg<\tlang-en'>" ); 1162 * $p->next_tag(); 1163 * foreach ( $p->class_list() as $class_name ) { 1164 * echo "{$class_name} "; 1165 * } 1166 * // Outputs: "free <egg> lang-en " 1167 * 1168 * @since 6.4.0 1169 */ 1170 public function class_list() { 1171 if ( self::STATE_MATCHED_TAG !== $this->parser_state ) { 1172 return; 1173 } 1174 1175 /** @var string $class contains the string value of the class attribute, with character references decoded. */ 1176 $class = $this->get_attribute( 'class' ); 1177 1178 if ( ! is_string( $class ) ) { 1179 return; 1180 } 1181 1182 $seen = array(); 1183 1184 $is_quirks = self::QUIRKS_MODE === $this->compat_mode; 1185 1186 $at = 0; 1187 while ( $at < strlen( $class ) ) { 1188 // Skip past any initial boundary characters. 1189 $at += strspn( $class, " \t\f\r\n", $at ); 1190 if ( $at >= strlen( $class ) ) { 1191 return; 1192 } 1193 1194 // Find the byte length until the next boundary. 1195 $length = strcspn( $class, " \t\f\r\n", $at ); 1196 if ( 0 === $length ) { 1197 return; 1198 } 1199 1200 $name = str_replace( "\x00", "\u{FFFD}", substr( $class, $at, $length ) ); 1201 if ( $is_quirks ) { 1202 $name = strtolower( $name ); 1203 } 1204 $at += $length; 1205 1206 /* 1207 * It's expected that the number of class names for a given tag is relatively small. 1208 * Given this, it is probably faster overall to scan an array for a value rather 1209 * than to use the class name as a key and check if it's a key of $seen. 1210 */ 1211 if ( in_array( $name, $seen, true ) ) { 1212 continue; 1213 } 1214 1215 $seen[] = $name; 1216 yield $name; 1217 } 1218 } 1219 1220 1221 /** 1222 * Returns if a matched tag contains the given ASCII case-insensitive class name. 1223 * 1224 * @since 6.4.0 1225 * 1226 * @param string $wanted_class Look for this CSS class name, ASCII case-insensitive. 1227 * @return bool|null Whether the matched tag contains the given class name, or null if not matched. 1228 */ 1229 public function has_class( $wanted_class ): ?bool { 1230 if ( self::STATE_MATCHED_TAG !== $this->parser_state ) { 1231 return null; 1232 } 1233 1234 $case_insensitive = self::QUIRKS_MODE === $this->compat_mode; 1235 1236 $wanted_length = strlen( $wanted_class ); 1237 foreach ( $this->class_list() as $class_name ) { 1238 if ( 1239 strlen( $class_name ) === $wanted_length && 1240 0 === substr_compare( $class_name, $wanted_class, 0, strlen( $wanted_class ), $case_insensitive ) 1241 ) { 1242 return true; 1243 } 1244 } 1245 1246 return false; 1247 } 1248 1249 1250 /** 1251 * Sets a bookmark in the HTML document. 1252 * 1253 * Bookmarks represent specific places or tokens in the HTML 1254 * document, such as a tag opener or closer. When applying 1255 * edits to a document, such as setting an attribute, the 1256 * text offsets of that token may shift; the bookmark is 1257 * kept updated with those shifts and remains stable unless 1258 * the entire span of text in which the token sits is removed. 1259 * 1260 * Release bookmarks when they are no longer needed. 1261 * 1262 * Example: 1263 * 1264 * <main><h2>Surprising fact you may not know!</h2></main> 1265 * ^ ^ 1266 * \-|-- this `H2` opener bookmark tracks the token 1267 * 1268 * <main class="clickbait"><h2>Surprising fact you may no… 1269 * ^ ^ 1270 * \-|-- it shifts with edits 1271 * 1272 * Bookmarks provide the ability to seek to a previously-scanned 1273 * place in the HTML document. This avoids the need to re-scan 1274 * the entire document. 1275 * 1276 * Example: 1277 * 1278 * <ul><li>One</li><li>Two</li><li>Three</li></ul> 1279 * ^^^^ 1280 * want to note this last item 1281 * 1282 * $p = new WP_HTML_Tag_Processor( $html ); 1283 * $in_list = false; 1284 * while ( $p->next_tag( array( 'tag_closers' => $in_list ? 'visit' : 'skip' ) ) ) { 1285 * if ( 'UL' === $p->get_tag() ) { 1286 * if ( $p->is_tag_closer() ) { 1287 * $in_list = false; 1288 * $p->set_bookmark( 'resume' ); 1289 * if ( $p->seek( 'last-li' ) ) { 1290 * $p->add_class( 'last-li' ); 1291 * } 1292 * $p->seek( 'resume' ); 1293 * $p->release_bookmark( 'last-li' ); 1294 * $p->release_bookmark( 'resume' ); 1295 * } else { 1296 * $in_list = true; 1297 * } 1298 * } 1299 * 1300 * if ( 'LI' === $p->get_tag() ) { 1301 * $p->set_bookmark( 'last-li' ); 1302 * } 1303 * } 1304 * 1305 * Bookmarks intentionally hide the internal string offsets 1306 * to which they refer. They are maintained internally as 1307 * updates are applied to the HTML document and therefore 1308 * retain their "position" - the location to which they 1309 * originally pointed. The inability to use bookmarks with 1310 * functions like `substr` is therefore intentional to guard 1311 * against accidentally breaking the HTML. 1312 * 1313 * Because bookmarks allocate memory and require processing 1314 * for every applied update, they are limited and require 1315 * a name. They should not be created with programmatically-made 1316 * names, such as "li_{$index}" with some loop. As a general 1317 * rule they should only be created with string-literal names 1318 * like "start-of-section" or "last-paragraph". 1319 * 1320 * Bookmarks are a powerful tool to enable complicated behavior. 1321 * Consider double-checking that you need this tool if you are 1322 * reaching for it, as inappropriate use could lead to broken 1323 * HTML structure or unwanted processing overhead. 1324 * 1325 * @since 6.2.0 1326 * 1327 * @param string $name Identifies this particular bookmark. 1328 * @return bool Whether the bookmark was successfully created. 1329 */ 1330 public function set_bookmark( $name ): bool { 1331 // It only makes sense to set a bookmark if the parser has paused on a concrete token. 1332 if ( 1333 self::STATE_COMPLETE === $this->parser_state || 1334 self::STATE_INCOMPLETE_INPUT === $this->parser_state 1335 ) { 1336 return false; 1337 } 1338 1339 if ( ! array_key_exists( $name, $this->bookmarks ) && count( $this->bookmarks ) >= static::MAX_BOOKMARKS ) { 1340 _doing_it_wrong( 1341 __METHOD__, 1342 __( 'Too many bookmarks: cannot create any more.' ), 1343 '6.2.0' 1344 ); 1345 return false; 1346 } 1347 1348 $this->bookmarks[ $name ] = new WP_HTML_Span( $this->token_starts_at, $this->token_length ); 1349 1350 return true; 1351 } 1352 1353 1354 /** 1355 * Removes a bookmark that is no longer needed. 1356 * 1357 * Releasing a bookmark frees up the small 1358 * performance overhead it requires. 1359 * 1360 * @param string $name Name of the bookmark to remove. 1361 * @return bool Whether the bookmark already existed before removal. 1362 */ 1363 public function release_bookmark( $name ): bool { 1364 if ( ! array_key_exists( $name, $this->bookmarks ) ) { 1365 return false; 1366 } 1367 1368 unset( $this->bookmarks[ $name ] ); 1369 1370 return true; 1371 } 1372 1373 /** 1374 * Skips contents of generic rawtext elements. 1375 * 1376 * @since 6.3.2 1377 * 1378 * @see https://html.spec.whatwg.org/#generic-raw-text-element-parsing-algorithm 1379 * 1380 * @param string $tag_name The uppercase tag name which will close the RAWTEXT region. 1381 * @return bool Whether an end to the RAWTEXT region was found before the end of the document. 1382 */ 1383 private function skip_rawtext( string $tag_name ): bool { 1384 /* 1385 * These two functions distinguish themselves on whether character references are 1386 * decoded, and since functionality to read the inner markup isn't supported, it's 1387 * not necessary to implement these two functions separately. 1388 */ 1389 return $this->skip_rcdata( $tag_name ); 1390 } 1391 1392 /** 1393 * Skips contents of RCDATA elements, namely title and textarea tags. 1394 * 1395 * @since 6.2.0 1396 * 1397 * @see https://html.spec.whatwg.org/multipage/parsing.html#rcdata-state 1398 * 1399 * @param string $tag_name The uppercase tag name which will close the RCDATA region. 1400 * @return bool Whether an end to the RCDATA region was found before the end of the document. 1401 */ 1402 private function skip_rcdata( string $tag_name ): bool { 1403 $html = $this->html; 1404 $doc_length = strlen( $html ); 1405 $tag_length = strlen( $tag_name ); 1406 1407 $at = $this->bytes_already_parsed; 1408 1409 while ( false !== $at && $at < $doc_length ) { 1410 $at = strpos( $this->html, '</', $at ); 1411 $this->tag_name_starts_at = $at; 1412 1413 // Fail if there is no possible tag closer. 1414 if ( false === $at || ( $at + $tag_length ) >= $doc_length ) { 1415 return false; 1416 } 1417 1418 $at += 2; 1419 1420 /* 1421 * Find a case-insensitive match to the tag name. 1422 * 1423 * Because tag names are limited to US-ASCII there is no 1424 * need to perform any kind of Unicode normalization when 1425 * comparing; any character which could be impacted by such 1426 * normalization could not be part of a tag name. 1427 */ 1428 for ( $i = 0; $i < $tag_length; $i++ ) { 1429 $tag_char = $tag_name[ $i ]; 1430 $html_char = $html[ $at + $i ]; 1431 1432 if ( $html_char !== $tag_char && strtoupper( $html_char ) !== $tag_char ) { 1433 $at += $i; 1434 continue 2; 1435 } 1436 } 1437 1438 $at += $tag_length; 1439 $this->bytes_already_parsed = $at; 1440 1441 if ( $at >= strlen( $html ) ) { 1442 return false; 1443 } 1444 1445 /* 1446 * Ensure that the tag name terminates to avoid matching on 1447 * substrings of a longer tag name. For example, the sequence 1448 * "</textarearug" should not match for "</textarea" even 1449 * though "textarea" is found within the text. 1450 */ 1451 $c = $html[ $at ]; 1452 if ( ' ' !== $c && "\t" !== $c && "\r" !== $c && "\n" !== $c && '/' !== $c && '>' !== $c ) { 1453 continue; 1454 } 1455 1456 while ( $this->parse_next_attribute() ) { 1457 continue; 1458 } 1459 1460 $at = $this->bytes_already_parsed; 1461 if ( $at >= strlen( $this->html ) ) { 1462 return false; 1463 } 1464 1465 if ( '>' === $html[ $at ] ) { 1466 $this->bytes_already_parsed = $at + 1; 1467 return true; 1468 } 1469 1470 if ( $at + 1 >= strlen( $this->html ) ) { 1471 return false; 1472 } 1473 1474 if ( '/' === $html[ $at ] && '>' === $html[ $at + 1 ] ) { 1475 $this->bytes_already_parsed = $at + 2; 1476 return true; 1477 } 1478 } 1479 1480 return false; 1481 } 1482 1483 /** 1484 * Skips contents of script tags. 1485 * 1486 * @since 6.2.0 1487 * 1488 * @return bool Whether the script tag was closed before the end of the document. 1489 */ 1490 private function skip_script_data(): bool { 1491 $state = 'unescaped'; 1492 $html = $this->html; 1493 $doc_length = strlen( $html ); 1494 $at = $this->bytes_already_parsed; 1495 1496 while ( false !== $at && $at < $doc_length ) { 1497 $at += strcspn( $html, '-<', $at ); 1498 1499 /* 1500 * Optimization: Terminating a complete script element requires at least eight 1501 * additional bytes in the document. Some checks below may cause local escaped 1502 * state transitions when processing shorter strings, but those transitions are 1503 * irrelevant if the script tag is incomplete and the function must return false. 1504 * 1505 * This may need updating if those transitions become significant or exported from 1506 * this function in some way, such as when building safe methods to embed JavaScript 1507 * or data inside a SCRIPT element. 1508 * 1509 * $at may be here. 1510 * ↓ 1511 * ...</script> 1512 * ╰──┬───╯ 1513 * $at + 8 additional bytes are required for a non-false return value. 1514 * 1515 * This single check eliminates the need to check lengths for the shorter spans: 1516 * 1517 * $at may be here. 1518 * ↓ 1519 * <script><!-- --></script> 1520 * ├╯ 1521 * $at + 2 additional characters does not require a length check. 1522 * 1523 * The transition from "escaped" to "unescaped" is not relevant if the document ends: 1524 * 1525 * $at may be here. 1526 * ↓ 1527 * <script><!-- -->[[END-OF-DOCUMENT]] 1528 * ╰──┬───╯ 1529 * $at + 8 additional bytes is not satisfied, return false. 1530 */ 1531 if ( $at + 8 >= $doc_length ) { 1532 return false; 1533 } 1534 1535 /* 1536 * For all script states a "-->" transitions 1537 * back into the normal unescaped script mode, 1538 * even if that's the current state. 1539 */ 1540 if ( 1541 '-' === $html[ $at ] && 1542 '-' === $html[ $at + 1 ] && 1543 '>' === $html[ $at + 2 ] 1544 ) { 1545 $at += 3; 1546 $state = 'unescaped'; 1547 continue; 1548 } 1549 1550 /* 1551 * Everything of interest past here starts with "<". 1552 * Check this character and advance position regardless. 1553 */ 1554 if ( '<' !== $html[ $at++ ] ) { 1555 continue; 1556 } 1557 1558 /* 1559 * Unlike with "-->", the "<!--" only transitions 1560 * into the escaped mode if not already there. 1561 * 1562 * Inside the escaped modes it will be ignored; and 1563 * should never break out of the double-escaped 1564 * mode and back into the escaped mode. 1565 * 1566 * While this requires a mode change, it does not 1567 * impact the parsing otherwise, so continue 1568 * parsing after updating the state. 1569 */ 1570 if ( 1571 '!' === $html[ $at ] && 1572 '-' === $html[ $at + 1 ] && 1573 '-' === $html[ $at + 2 ] 1574 ) { 1575 $at += 3; 1576 $state = 'unescaped' === $state ? 'escaped' : $state; 1577 continue; 1578 } 1579 1580 if ( '/' === $html[ $at ] ) { 1581 $closer_potentially_starts_at = $at - 1; 1582 $is_closing = true; 1583 ++$at; 1584 } else { 1585 $is_closing = false; 1586 } 1587 1588 /* 1589 * At this point the only remaining state-changes occur with the 1590 * <script> and </script> tags; unless one of these appears next, 1591 * proceed scanning to the next potential token in the text. 1592 */ 1593 if ( ! ( 1594 ( 's' === $html[ $at ] || 'S' === $html[ $at ] ) && 1595 ( 'c' === $html[ $at + 1 ] || 'C' === $html[ $at + 1 ] ) && 1596 ( 'r' === $html[ $at + 2 ] || 'R' === $html[ $at + 2 ] ) && 1597 ( 'i' === $html[ $at + 3 ] || 'I' === $html[ $at + 3 ] ) && 1598 ( 'p' === $html[ $at + 4 ] || 'P' === $html[ $at + 4 ] ) && 1599 ( 't' === $html[ $at + 5 ] || 'T' === $html[ $at + 5 ] ) 1600 ) ) { 1601 ++$at; 1602 continue; 1603 } 1604 1605 /* 1606 * Ensure that the script tag terminates to avoid matching on 1607 * substrings of a non-match. For example, the sequence 1608 * "<script123" should not end a script region even though 1609 * "<script" is found within the text. 1610 */ 1611 $at += 6; 1612 $c = $html[ $at ]; 1613 if ( ' ' !== $c && "\t" !== $c && "\r" !== $c && "\n" !== $c && '/' !== $c && '>' !== $c ) { 1614 ++$at; 1615 continue; 1616 } 1617 1618 if ( 'escaped' === $state && ! $is_closing ) { 1619 $state = 'double-escaped'; 1620 continue; 1621 } 1622 1623 if ( 'double-escaped' === $state && $is_closing ) { 1624 $state = 'escaped'; 1625 continue; 1626 } 1627 1628 if ( $is_closing ) { 1629 $this->bytes_already_parsed = $closer_potentially_starts_at; 1630 $this->tag_name_starts_at = $closer_potentially_starts_at; 1631 if ( $this->bytes_already_parsed >= $doc_length ) { 1632 return false; 1633 } 1634 1635 while ( $this->parse_next_attribute() ) { 1636 continue; 1637 } 1638 1639 if ( $this->bytes_already_parsed >= $doc_length ) { 1640 return false; 1641 } 1642 1643 if ( '>' === $html[ $this->bytes_already_parsed ] ) { 1644 ++$this->bytes_already_parsed; 1645 return true; 1646 } 1647 } 1648 1649 ++$at; 1650 } 1651 1652 return false; 1653 } 1654 1655 /** 1656 * Parses the next tag. 1657 * 1658 * This will find and start parsing the next tag, including 1659 * the opening `<`, the potential closer `/`, and the tag 1660 * name. It does not parse the attributes or scan to the 1661 * closing `>`; these are left for other methods. 1662 * 1663 * @since 6.2.0 1664 * @since 6.2.1 Support abruptly-closed comments, invalid-tag-closer-comments, and empty elements. 1665 * 1666 * @return bool Whether a tag was found before the end of the document. 1667 */ 1668 private function parse_next_tag(): bool { 1669 $this->after_tag(); 1670 1671 $html = $this->html; 1672 $doc_length = strlen( $html ); 1673 $was_at = $this->bytes_already_parsed; 1674 $at = $was_at; 1675 1676 while ( $at < $doc_length ) { 1677 $at = strpos( $html, '<', $at ); 1678 if ( false === $at ) { 1679 break; 1680 } 1681 1682 if ( $at > $was_at ) { 1683 /* 1684 * A "<" normally starts a new HTML tag or syntax token, but in cases where the 1685 * following character can't produce a valid token, the "<" is instead treated 1686 * as plaintext and the parser should skip over it. This avoids a problem when 1687 * following earlier practices of typing emoji with text, e.g. "<3". This 1688 * should be a heart, not a tag. It's supposed to be rendered, not hidden. 1689 * 1690 * At this point the parser checks if this is one of those cases and if it is 1691 * will continue searching for the next "<" in search of a token boundary. 1692 * 1693 * @see https://html.spec.whatwg.org/#tag-open-state 1694 */ 1695 if ( 1 !== strspn( $html, '!/?abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ', $at + 1, 1 ) ) { 1696 ++$at; 1697 continue; 1698 } 1699 1700 $this->parser_state = self::STATE_TEXT_NODE; 1701 $this->token_starts_at = $was_at; 1702 $this->token_length = $at - $was_at; 1703 $this->text_starts_at = $was_at; 1704 $this->text_length = $this->token_length; 1705 $this->bytes_already_parsed = $at; 1706 return true; 1707 } 1708 1709 $this->token_starts_at = $at; 1710 1711 if ( $at + 1 < $doc_length && '/' === $this->html[ $at + 1 ] ) { 1712 $this->is_closing_tag = true; 1713 ++$at; 1714 } else { 1715 $this->is_closing_tag = false; 1716 } 1717 1718 /* 1719 * HTML tag names must start with [a-zA-Z] otherwise they are not tags. 1720 * For example, "<3" is rendered as text, not a tag opener. If at least 1721 * one letter follows the "<" then _it is_ a tag, but if the following 1722 * character is anything else it _is not a tag_. 1723 * 1724 * It's not uncommon to find non-tags starting with `<` in an HTML 1725 * document, so it's good for performance to make this pre-check before 1726 * continuing to attempt to parse a tag name. 1727 * 1728 * Reference: 1729 * * https://html.spec.whatwg.org/multipage/parsing.html#data-state 1730 * * https://html.spec.whatwg.org/multipage/parsing.html#tag-open-state 1731 */ 1732 $tag_name_prefix_length = strspn( $html, 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ', $at + 1 ); 1733 if ( $tag_name_prefix_length > 0 ) { 1734 ++$at; 1735 $this->parser_state = self::STATE_MATCHED_TAG; 1736 $this->tag_name_starts_at = $at; 1737 $this->tag_name_length = $tag_name_prefix_length + strcspn( $html, " \t\f\r\n/>", $at + $tag_name_prefix_length ); 1738 $this->bytes_already_parsed = $at + $this->tag_name_length; 1739 return true; 1740 } 1741 1742 /* 1743 * Abort if no tag is found before the end of 1744 * the document. There is nothing left to parse. 1745 */ 1746 if ( $at + 1 >= $doc_length ) { 1747 $this->parser_state = self::STATE_INCOMPLETE_INPUT; 1748 1749 return false; 1750 } 1751 1752 /* 1753 * `<!` transitions to markup declaration open state 1754 * https://html.spec.whatwg.org/multipage/parsing.html#markup-declaration-open-state 1755 */ 1756 if ( ! $this->is_closing_tag && '!' === $html[ $at + 1 ] ) { 1757 /* 1758 * `<!--` transitions to a comment state – apply further comment rules. 1759 * https://html.spec.whatwg.org/multipage/parsing.html#tag-open-state 1760 */ 1761 if ( 0 === substr_compare( $html, '--', $at + 2, 2 ) ) { 1762 $closer_at = $at + 4; 1763 // If it's not possible to close the comment then there is nothing more to scan. 1764 if ( $doc_length <= $closer_at ) { 1765 $this->parser_state = self::STATE_INCOMPLETE_INPUT; 1766 1767 return false; 1768 } 1769 1770 // Abruptly-closed empty comments are a sequence of dashes followed by `>`. 1771 $span_of_dashes = strspn( $html, '-', $closer_at ); 1772 if ( '>' === $html[ $closer_at + $span_of_dashes ] ) { 1773 /* 1774 * @todo When implementing `set_modifiable_text()` ensure that updates to this token 1775 * don't break the syntax for short comments, e.g. `<!--->`. Unlike other comment 1776 * and bogus comment syntax, these leave no clear insertion point for text and 1777 * they need to be modified specially in order to contain text. E.g. to store 1778 * `?` as the modifiable text, the `<!--->` needs to become `<!--?-->`, which 1779 * involves inserting an additional `-` into the token after the modifiable text. 1780 */ 1781 $this->parser_state = self::STATE_COMMENT; 1782 $this->comment_type = self::COMMENT_AS_ABRUPTLY_CLOSED_COMMENT; 1783 $this->token_length = $closer_at + $span_of_dashes + 1 - $this->token_starts_at; 1784 1785 // Only provide modifiable text if the token is long enough to contain it. 1786 if ( $span_of_dashes >= 2 ) { 1787 $this->comment_type = self::COMMENT_AS_HTML_COMMENT; 1788 $this->text_starts_at = $this->token_starts_at + 4; 1789 $this->text_length = $span_of_dashes - 2; 1790 } 1791 1792 $this->bytes_already_parsed = $closer_at + $span_of_dashes + 1; 1793 return true; 1794 } 1795 1796 /* 1797 * Comments may be closed by either a --> or an invalid --!>. 1798 * The first occurrence closes the comment. 1799 * 1800 * See https://html.spec.whatwg.org/#parse-error-incorrectly-closed-comment 1801 */ 1802 --$closer_at; // Pre-increment inside condition below reduces risk of accidental infinite looping. 1803 while ( ++$closer_at < $doc_length ) { 1804 $closer_at = strpos( $html, '--', $closer_at ); 1805 if ( false === $closer_at ) { 1806 $this->parser_state = self::STATE_INCOMPLETE_INPUT; 1807 1808 return false; 1809 } 1810 1811 if ( $closer_at + 2 < $doc_length && '>' === $html[ $closer_at + 2 ] ) { 1812 $this->parser_state = self::STATE_COMMENT; 1813 $this->comment_type = self::COMMENT_AS_HTML_COMMENT; 1814 $this->token_length = $closer_at + 3 - $this->token_starts_at; 1815 $this->text_starts_at = $this->token_starts_at + 4; 1816 $this->text_length = $closer_at - $this->text_starts_at; 1817 $this->bytes_already_parsed = $closer_at + 3; 1818 return true; 1819 } 1820 1821 if ( 1822 $closer_at + 3 < $doc_length && 1823 '!' === $html[ $closer_at + 2 ] && 1824 '>' === $html[ $closer_at + 3 ] 1825 ) { 1826 $this->parser_state = self::STATE_COMMENT; 1827 $this->comment_type = self::COMMENT_AS_HTML_COMMENT; 1828 $this->token_length = $closer_at + 4 - $this->token_starts_at; 1829 $this->text_starts_at = $this->token_starts_at + 4; 1830 $this->text_length = $closer_at - $this->text_starts_at; 1831 $this->bytes_already_parsed = $closer_at + 4; 1832 return true; 1833 } 1834 } 1835 } 1836 1837 /* 1838 * `<!DOCTYPE` transitions to DOCTYPE state – skip to the nearest > 1839 * These are ASCII-case-insensitive. 1840 * https://html.spec.whatwg.org/multipage/parsing.html#tag-open-state 1841 */ 1842 if ( 1843 $doc_length > $at + 8 && 1844 ( 'D' === $html[ $at + 2 ] || 'd' === $html[ $at + 2 ] ) && 1845 ( 'O' === $html[ $at + 3 ] || 'o' === $html[ $at + 3 ] ) && 1846 ( 'C' === $html[ $at + 4 ] || 'c' === $html[ $at + 4 ] ) && 1847 ( 'T' === $html[ $at + 5 ] || 't' === $html[ $at + 5 ] ) && 1848 ( 'Y' === $html[ $at + 6 ] || 'y' === $html[ $at + 6 ] ) && 1849 ( 'P' === $html[ $at + 7 ] || 'p' === $html[ $at + 7 ] ) && 1850 ( 'E' === $html[ $at + 8 ] || 'e' === $html[ $at + 8 ] ) 1851 ) { 1852 $closer_at = strpos( $html, '>', $at + 9 ); 1853 if ( false === $closer_at ) { 1854 $this->parser_state = self::STATE_INCOMPLETE_INPUT; 1855 1856 return false; 1857 } 1858 1859 $this->parser_state = self::STATE_DOCTYPE; 1860 $this->token_length = $closer_at + 1 - $this->token_starts_at; 1861 $this->text_starts_at = $this->token_starts_at + 9; 1862 $this->text_length = $closer_at - $this->text_starts_at; 1863 $this->bytes_already_parsed = $closer_at + 1; 1864 return true; 1865 } 1866 1867 if ( 1868 'html' !== $this->parsing_namespace && 1869 strlen( $html ) > $at + 8 && 1870 '[' === $html[ $at + 2 ] && 1871 'C' === $html[ $at + 3 ] && 1872 'D' === $html[ $at + 4 ] && 1873 'A' === $html[ $at + 5 ] && 1874 'T' === $html[ $at + 6 ] && 1875 'A' === $html[ $at + 7 ] && 1876 '[' === $html[ $at + 8 ] 1877 ) { 1878 $closer_at = strpos( $html, ']]>', $at + 9 ); 1879 if ( false === $closer_at ) { 1880 $this->parser_state = self::STATE_INCOMPLETE_INPUT; 1881 1882 return false; 1883 } 1884 1885 $this->parser_state = self::STATE_CDATA_NODE; 1886 $this->text_starts_at = $at + 9; 1887 $this->text_length = $closer_at - $this->text_starts_at; 1888 $this->token_length = $closer_at + 3 - $this->token_starts_at; 1889 $this->bytes_already_parsed = $closer_at + 3; 1890 return true; 1891 } 1892 1893 /* 1894 * Anything else here is an incorrectly-opened comment and transitions 1895 * to the bogus comment state - skip to the nearest >. If no closer is 1896 * found then the HTML was truncated inside the markup declaration. 1897 */ 1898 $closer_at = strpos( $html, '>', $at + 1 ); 1899 if ( false === $closer_at ) { 1900 $this->parser_state = self::STATE_INCOMPLETE_INPUT; 1901 1902 return false; 1903 } 1904 1905 $this->parser_state = self::STATE_COMMENT; 1906 $this->comment_type = self::COMMENT_AS_INVALID_HTML; 1907 $this->token_length = $closer_at + 1 - $this->token_starts_at; 1908 $this->text_starts_at = $this->token_starts_at + 2; 1909 $this->text_length = $closer_at - $this->text_starts_at; 1910 $this->bytes_already_parsed = $closer_at + 1; 1911 1912 /* 1913 * Identify nodes that would be CDATA if HTML had CDATA sections. 1914 * 1915 * This section must occur after identifying the bogus comment end 1916 * because in an HTML parser it will span to the nearest `>`, even 1917 * if there's no `]]>` as would be required in an XML document. It 1918 * is therefore not possible to parse a CDATA section containing 1919 * a `>` in the HTML syntax. 1920 * 1921 * Inside foreign elements there is a discrepancy between browsers 1922 * and the specification on this. 1923 * 1924 * @todo Track whether the Tag Processor is inside a foreign element 1925 * and require the proper closing `]]>` in those cases. 1926 */ 1927 if ( 1928 $this->token_length >= 10 && 1929 '[' === $html[ $this->token_starts_at + 2 ] && 1930 'C' === $html[ $this->token_starts_at + 3 ] && 1931 'D' === $html[ $this->token_starts_at + 4 ] && 1932 'A' === $html[ $this->token_starts_at + 5 ] && 1933 'T' === $html[ $this->token_starts_at + 6 ] && 1934 'A' === $html[ $this->token_starts_at + 7 ] && 1935 '[' === $html[ $this->token_starts_at + 8 ] && 1936 ']' === $html[ $closer_at - 1 ] && 1937 ']' === $html[ $closer_at - 2 ] 1938 ) { 1939 $this->parser_state = self::STATE_COMMENT; 1940 $this->comment_type = self::COMMENT_AS_CDATA_LOOKALIKE; 1941 $this->text_starts_at += 7; 1942 $this->text_length -= 9; 1943 } 1944 1945 return true; 1946 } 1947 1948 /* 1949 * </> is a missing end tag name, which is ignored. 1950 * 1951 * This was also known as the "presumptuous empty tag" 1952 * in early discussions as it was proposed to close 1953 * the nearest previous opening tag. 1954 * 1955 * See https://html.spec.whatwg.org/#parse-error-missing-end-tag-name 1956 */ 1957 if ( '>' === $html[ $at + 1 ] ) { 1958 // `<>` is interpreted as plaintext. 1959 if ( ! $this->is_closing_tag ) { 1960 ++$at; 1961 continue; 1962 } 1963 1964 $this->parser_state = self::STATE_PRESUMPTUOUS_TAG; 1965 $this->token_length = $at + 2 - $this->token_starts_at; 1966 $this->bytes_already_parsed = $at + 2; 1967 return true; 1968 } 1969 1970 /* 1971 * `<?` transitions to a bogus comment state – skip to the nearest > 1972 * See https://html.spec.whatwg.org/multipage/parsing.html#tag-open-state 1973 */ 1974 if ( ! $this->is_closing_tag && '?' === $html[ $at + 1 ] ) { 1975 $closer_at = strpos( $html, '>', $at + 2 ); 1976 if ( false === $closer_at ) { 1977 $this->parser_state = self::STATE_INCOMPLETE_INPUT; 1978 1979 return false; 1980 } 1981 1982 $this->parser_state = self::STATE_COMMENT; 1983 $this->comment_type = self::COMMENT_AS_INVALID_HTML; 1984 $this->token_length = $closer_at + 1 - $this->token_starts_at; 1985 $this->text_starts_at = $this->token_starts_at + 2; 1986 $this->text_length = $closer_at - $this->text_starts_at; 1987 $this->bytes_already_parsed = $closer_at + 1; 1988 1989 /* 1990 * Identify a Processing Instruction node were HTML to have them. 1991 * 1992 * This section must occur after identifying the bogus comment end 1993 * because in an HTML parser it will span to the nearest `>`, even 1994 * if there's no `?>` as would be required in an XML document. It 1995 * is therefore not possible to parse a Processing Instruction node 1996 * containing a `>` in the HTML syntax. 1997 * 1998 * XML allows for more target names, but this code only identifies 1999 * those with ASCII-representable target names. This means that it 2000 * may identify some Processing Instruction nodes as bogus comments, 2001 * but it will not misinterpret the HTML structure. By limiting the 2002 * identification to these target names the Tag Processor can avoid 2003 * the need to start parsing UTF-8 sequences. 2004 * 2005 * > NameStartChar ::= ":" | [A-Z] | "_" | [a-z] | [#xC0-#xD6] | [#xD8-#xF6] | [#xF8-#x2FF] | 2006 * [#x370-#x37D] | [#x37F-#x1FFF] | [#x200C-#x200D] | [#x2070-#x218F] | 2007 * [#x2C00-#x2FEF] | [#x3001-#xD7FF] | [#xF900-#xFDCF] | [#xFDF0-#xFFFD] | 2008 * [#x10000-#xEFFFF] 2009 * > NameChar ::= NameStartChar | "-" | "." | [0-9] | #xB7 | [#x0300-#x036F] | [#x203F-#x2040] 2010 * 2011 * @todo Processing instruction nodes in SGML may contain any kind of markup. XML defines a 2012 * special case with `<?xml ... ?>` syntax, but the `?` is part of the bogus comment. 2013 * 2014 * @see https://www.w3.org/TR/2006/REC-xml11-20060816/#NT-PITarget 2015 */ 2016 if ( $this->token_length >= 5 && '?' === $html[ $closer_at - 1 ] ) { 2017 $comment_text = substr( $html, $this->token_starts_at + 2, $this->token_length - 4 ); 2018 $pi_target_length = strspn( $comment_text, 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ:_' ); 2019 2020 if ( 0 < $pi_target_length ) { 2021 $pi_target_length += strspn( $comment_text, 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789:_-.', $pi_target_length ); 2022 2023 $this->comment_type = self::COMMENT_AS_PI_NODE_LOOKALIKE; 2024 $this->tag_name_starts_at = $this->token_starts_at + 2; 2025 $this->tag_name_length = $pi_target_length; 2026 $this->text_starts_at += $pi_target_length; 2027 $this->text_length -= $pi_target_length + 1; 2028 } 2029 } 2030 2031 return true; 2032 } 2033 2034 /* 2035 * If a non-alpha starts the tag name in a tag closer it's a comment. 2036 * Find the first `>`, which closes the comment. 2037 * 2038 * This parser classifies these particular comments as special "funky comments" 2039 * which are made available for further processing. 2040 * 2041 * See https://html.spec.whatwg.org/#parse-error-invalid-first-character-of-tag-name 2042 */ 2043 if ( $this->is_closing_tag ) { 2044 // No chance of finding a closer. 2045 if ( $at + 3 > $doc_length ) { 2046 $this->parser_state = self::STATE_INCOMPLETE_INPUT; 2047 2048 return false; 2049 } 2050 2051 $closer_at = strpos( $html, '>', $at + 2 ); 2052 if ( false === $closer_at ) { 2053 $this->parser_state = self::STATE_INCOMPLETE_INPUT; 2054 2055 return false; 2056 } 2057 2058 $this->parser_state = self::STATE_FUNKY_COMMENT; 2059 $this->token_length = $closer_at + 1 - $this->token_starts_at; 2060 $this->text_starts_at = $this->token_starts_at + 2; 2061 $this->text_length = $closer_at - $this->text_starts_at; 2062 $this->bytes_already_parsed = $closer_at + 1; 2063 return true; 2064 } 2065 2066 ++$at; 2067 } 2068 2069 /* 2070 * This does not imply an incomplete parse; it indicates that there 2071 * can be nothing left in the document other than a #text node. 2072 */ 2073 $this->parser_state = self::STATE_TEXT_NODE; 2074 $this->token_starts_at = $was_at; 2075 $this->token_length = $doc_length - $was_at; 2076 $this->text_starts_at = $was_at; 2077 $this->text_length = $this->token_length; 2078 $this->bytes_already_parsed = $doc_length; 2079 return true; 2080 } 2081 2082 /** 2083 * Parses the next attribute. 2084 * 2085 * @since 6.2.0 2086 * 2087 * @return bool Whether an attribute was found before the end of the document. 2088 */ 2089 private function parse_next_attribute(): bool { 2090 $doc_length = strlen( $this->html ); 2091 2092 // Skip whitespace and slashes. 2093 $this->bytes_already_parsed += strspn( $this->html, " \t\f\r\n/", $this->bytes_already_parsed ); 2094 if ( $this->bytes_already_parsed >= $doc_length ) { 2095 $this->parser_state = self::STATE_INCOMPLETE_INPUT; 2096 2097 return false; 2098 } 2099 2100 /* 2101 * Treat the equal sign as a part of the attribute 2102 * name if it is the first encountered byte. 2103 * 2104 * @see https://html.spec.whatwg.org/multipage/parsing.html#before-attribute-name-state 2105 */ 2106 $name_length = '=' === $this->html[ $this->bytes_already_parsed ] 2107 ? 1 + strcspn( $this->html, "=/> \t\f\r\n", $this->bytes_already_parsed + 1 ) 2108 : strcspn( $this->html, "=/> \t\f\r\n", $this->bytes_already_parsed ); 2109 2110 // No attribute, just tag closer. 2111 if ( 0 === $name_length || $this->bytes_already_parsed + $name_length >= $doc_length ) { 2112 return false; 2113 } 2114 2115 $attribute_start = $this->bytes_already_parsed; 2116 $attribute_name = substr( $this->html, $attribute_start, $name_length ); 2117 $this->bytes_already_parsed += $name_length; 2118 if ( $this->bytes_already_parsed >= $doc_length ) { 2119 $this->parser_state = self::STATE_INCOMPLETE_INPUT; 2120 2121 return false; 2122 } 2123 2124 $this->skip_whitespace(); 2125 if ( $this->bytes_already_parsed >= $doc_length ) { 2126 $this->parser_state = self::STATE_INCOMPLETE_INPUT; 2127 2128 return false; 2129 } 2130 2131 $has_value = '=' === $this->html[ $this->bytes_already_parsed ]; 2132 if ( $has_value ) { 2133 ++$this->bytes_already_parsed; 2134 $this->skip_whitespace(); 2135 if ( $this->bytes_already_parsed >= $doc_length ) { 2136 $this->parser_state = self::STATE_INCOMPLETE_INPUT; 2137 2138 return false; 2139 } 2140 2141 switch ( $this->html[ $this->bytes_already_parsed ] ) { 2142 case "'": 2143 case '"': 2144 $quote = $this->html[ $this->bytes_already_parsed ]; 2145 $value_start = $this->bytes_already_parsed + 1; 2146 $end_quote_at = strpos( $this->html, $quote, $value_start ); 2147 $end_quote_at = false === $end_quote_at ? $doc_length : $end_quote_at; 2148 $value_length = $end_quote_at - $value_start; 2149 $attribute_end = $end_quote_at + 1; 2150 $this->bytes_already_parsed = $attribute_end; 2151 break; 2152 2153 default: 2154 $value_start = $this->bytes_already_parsed; 2155 $value_length = strcspn( $this->html, "> \t\f\r\n", $value_start ); 2156 $attribute_end = $value_start + $value_length; 2157 $this->bytes_already_parsed = $attribute_end; 2158 } 2159 } else { 2160 $value_start = $this->bytes_already_parsed; 2161 $value_length = 0; 2162 $attribute_end = $attribute_start + $name_length; 2163 } 2164 2165 if ( $attribute_end >= $doc_length ) { 2166 $this->parser_state = self::STATE_INCOMPLETE_INPUT; 2167 2168 return false; 2169 } 2170 2171 if ( $this->is_closing_tag ) { 2172 return true; 2173 } 2174 2175 /* 2176 * > There must never be two or more attributes on 2177 * > the same start tag whose names are an ASCII 2178 * > case-insensitive match for each other. 2179 * - HTML 5 spec 2180 * 2181 * @see https://html.spec.whatwg.org/multipage/syntax.html#attributes-2:ascii-case-insensitive 2182 */ 2183 $comparable_name = strtolower( $attribute_name ); 2184 2185 // If an attribute is listed many times, only use the first declaration and ignore the rest. 2186 if ( ! isset( $this->attributes[ $comparable_name ] ) ) { 2187 $this->attributes[ $comparable_name ] = new WP_HTML_Attribute_Token( 2188 $attribute_name, 2189 $value_start, 2190 $value_length, 2191 $attribute_start, 2192 $attribute_end - $attribute_start, 2193 ! $has_value 2194 ); 2195 2196 return true; 2197 } 2198 2199 /* 2200 * Track the duplicate attributes so if we remove it, all disappear together. 2201 * 2202 * While `$this->duplicated_attributes` could always be stored as an `array()`, 2203 * which would simplify the logic here, storing a `null` and only allocating 2204 * an array when encountering duplicates avoids needless allocations in the 2205 * normative case of parsing tags with no duplicate attributes. 2206 */ 2207 $duplicate_span = new WP_HTML_Span( $attribute_start, $attribute_end - $attribute_start ); 2208 if ( null === $this->duplicate_attributes ) { 2209 $this->duplicate_attributes = array( $comparable_name => array( $duplicate_span ) ); 2210 } elseif ( ! isset( $this->duplicate_attributes[ $comparable_name ] ) ) { 2211 $this->duplicate_attributes[ $comparable_name ] = array( $duplicate_span ); 2212 } else { 2213 $this->duplicate_attributes[ $comparable_name ][] = $duplicate_span; 2214 } 2215 2216 return true; 2217 } 2218 2219 /** 2220 * Move the internal cursor past any immediate successive whitespace. 2221 * 2222 * @since 6.2.0 2223 */ 2224 private function skip_whitespace(): void { 2225 $this->bytes_already_parsed += strspn( $this->html, " \t\f\r\n", $this->bytes_already_parsed ); 2226 } 2227 2228 /** 2229 * Applies attribute updates and cleans up once a tag is fully parsed. 2230 * 2231 * @since 6.2.0 2232 */ 2233 private function after_tag(): void { 2234 /* 2235 * There could be lexical updates enqueued for an attribute that 2236 * also exists on the next tag. In order to avoid conflating the 2237 * attributes across the two tags, lexical updates with names 2238 * need to be flushed to raw lexical updates. 2239 */ 2240 $this->class_name_updates_to_attributes_updates(); 2241 2242 /* 2243 * Purge updates if there are too many. The actual count isn't 2244 * scientific, but a few values from 100 to a few thousand were 2245 * tests to find a practically-useful limit. 2246 * 2247 * If the update queue grows too big, then the Tag Processor 2248 * will spend more time iterating through them and lose the 2249 * efficiency gains of deferring applying them. 2250 */ 2251 if ( 1000 < count( $this->lexical_updates ) ) { 2252 $this->get_updated_html(); 2253 } 2254 2255 foreach ( $this->lexical_updates as $name => $update ) { 2256 /* 2257 * Any updates appearing after the cursor should be applied 2258 * before proceeding, otherwise they may be overlooked. 2259 */ 2260 if ( $update->start >= $this->bytes_already_parsed ) { 2261 $this->get_updated_html(); 2262 break; 2263 } 2264 2265 if ( is_int( $name ) ) { 2266 continue; 2267 } 2268 2269 $this->lexical_updates[] = $update; 2270 unset( $this->lexical_updates[ $name ] ); 2271 } 2272 2273 $this->token_starts_at = null; 2274 $this->token_length = null; 2275 $this->tag_name_starts_at = null; 2276 $this->tag_name_length = null; 2277 $this->text_starts_at = 0; 2278 $this->text_length = 0; 2279 $this->is_closing_tag = null; 2280 $this->attributes = array(); 2281 $this->comment_type = null; 2282 $this->text_node_classification = self::TEXT_IS_GENERIC; 2283 $this->duplicate_attributes = null; 2284 } 2285 2286 /** 2287 * Converts class name updates into tag attributes updates 2288 * (they are accumulated in different data formats for performance). 2289 * 2290 * @since 6.2.0 2291 * 2292 * @see WP_HTML_Tag_Processor::$lexical_updates 2293 * @see WP_HTML_Tag_Processor::$classname_updates 2294 */ 2295 private function class_name_updates_to_attributes_updates(): void { 2296 if ( count( $this->classname_updates ) === 0 ) { 2297 return; 2298 } 2299 2300 $existing_class = $this->get_enqueued_attribute_value( 'class' ); 2301 if ( null === $existing_class || true === $existing_class ) { 2302 $existing_class = ''; 2303 } 2304 2305 if ( false === $existing_class && isset( $this->attributes['class'] ) ) { 2306 $existing_class = substr( 2307 $this->html, 2308 $this->attributes['class']->value_starts_at, 2309 $this->attributes['class']->value_length 2310 ); 2311 } 2312 2313 if ( false === $existing_class ) { 2314 $existing_class = ''; 2315 } 2316 2317 /** 2318 * Updated "class" attribute value. 2319 * 2320 * This is incrementally built while scanning through the existing class 2321 * attribute, skipping removed classes on the way, and then appending 2322 * added classes at the end. Only when finished processing will the 2323 * value contain the final new value. 2324 2325 * @var string $class 2326 */ 2327 $class = ''; 2328 2329 /** 2330 * Tracks the cursor position in the existing 2331 * class attribute value while parsing. 2332 * 2333 * @var int $at 2334 */ 2335 $at = 0; 2336 2337 /** 2338 * Indicates if there's any need to modify the existing class attribute. 2339 * 2340 * If a call to `add_class()` and `remove_class()` wouldn't impact 2341 * the `class` attribute value then there's no need to rebuild it. 2342 * For example, when adding a class that's already present or 2343 * removing one that isn't. 2344 * 2345 * This flag enables a performance optimization when none of the enqueued 2346 * class updates would impact the `class` attribute; namely, that the 2347 * processor can continue without modifying the input document, as if 2348 * none of the `add_class()` or `remove_class()` calls had been made. 2349 * 2350 * This flag is set upon the first change that requires a string update. 2351 * 2352 * @var bool $modified 2353 */ 2354 $modified = false; 2355 2356 $seen = array(); 2357 $to_remove = array(); 2358 $is_quirks = self::QUIRKS_MODE === $this->compat_mode; 2359 if ( $is_quirks ) { 2360 foreach ( $this->classname_updates as $updated_name => $action ) { 2361 if ( self::REMOVE_CLASS === $action ) { 2362 $to_remove[] = strtolower( $updated_name ); 2363 } 2364 } 2365 } else { 2366 foreach ( $this->classname_updates as $updated_name => $action ) { 2367 if ( self::REMOVE_CLASS === $action ) { 2368 $to_remove[] = $updated_name; 2369 } 2370 } 2371 } 2372 2373 // Remove unwanted classes by only copying the new ones. 2374 $existing_class_length = strlen( $existing_class ); 2375 while ( $at < $existing_class_length ) { 2376 // Skip to the first non-whitespace character. 2377 $ws_at = $at; 2378 $ws_length = strspn( $existing_class, " \t\f\r\n", $ws_at ); 2379 $at += $ws_length; 2380 2381 // Capture the class name – it's everything until the next whitespace. 2382 $name_length = strcspn( $existing_class, " \t\f\r\n", $at ); 2383 if ( 0 === $name_length ) { 2384 // If no more class names are found then that's the end. 2385 break; 2386 } 2387 2388 $name = substr( $existing_class, $at, $name_length ); 2389 $comparable_class_name = $is_quirks ? strtolower( $name ) : $name; 2390 $at += $name_length; 2391 2392 // If this class is marked for removal, remove it and move on to the next one. 2393 if ( in_array( $comparable_class_name, $to_remove, true ) ) { 2394 $modified = true; 2395 continue; 2396 } 2397 2398 // If a class has already been seen then skip it; it should not be added twice. 2399 if ( in_array( $comparable_class_name, $seen, true ) ) { 2400 continue; 2401 } 2402 2403 $seen[] = $comparable_class_name; 2404 2405 /* 2406 * Otherwise, append it to the new "class" attribute value. 2407 * 2408 * There are options for handling whitespace between tags. 2409 * Preserving the existing whitespace produces fewer changes 2410 * to the HTML content and should clarify the before/after 2411 * content when debugging the modified output. 2412 * 2413 * This approach contrasts normalizing the inter-class 2414 * whitespace to a single space, which might appear cleaner 2415 * in the output HTML but produce a noisier change. 2416 */ 2417 if ( '' !== $class ) { 2418 $class .= substr( $existing_class, $ws_at, $ws_length ); 2419 } 2420 $class .= $name; 2421 } 2422 2423 // Add new classes by appending those which haven't already been seen. 2424 foreach ( $this->classname_updates as $name => $operation ) { 2425 $comparable_name = $is_quirks ? strtolower( $name ) : $name; 2426 if ( self::ADD_CLASS === $operation && ! in_array( $comparable_name, $seen, true ) ) { 2427 $modified = true; 2428 2429 $class .= strlen( $class ) > 0 ? ' ' : ''; 2430 $class .= $name; 2431 } 2432 } 2433 2434 $this->classname_updates = array(); 2435 if ( ! $modified ) { 2436 return; 2437 } 2438 2439 if ( strlen( $class ) > 0 ) { 2440 $this->set_attribute( 'class', $class ); 2441 } else { 2442 $this->remove_attribute( 'class' ); 2443 } 2444 } 2445 2446 /** 2447 * Applies attribute updates to HTML document. 2448 * 2449 * @since 6.2.0 2450 * @since 6.2.1 Accumulates shift for internal cursor and passed pointer. 2451 * @since 6.3.0 Invalidate any bookmarks whose targets are overwritten. 2452 * 2453 * @param int $shift_this_point Accumulate and return shift for this position. 2454 * @return int How many bytes the given pointer moved in response to the updates. 2455 */ 2456 private function apply_attributes_updates( int $shift_this_point ): int { 2457 if ( ! count( $this->lexical_updates ) ) { 2458 return 0; 2459 } 2460 2461 $accumulated_shift_for_given_point = 0; 2462 2463 /* 2464 * Attribute updates can be enqueued in any order but updates 2465 * to the document must occur in lexical order; that is, each 2466 * replacement must be made before all others which follow it 2467 * at later string indices in the input document. 2468 * 2469 * Sorting avoid making out-of-order replacements which 2470 * can lead to mangled output, partially-duplicated 2471 * attributes, and overwritten attributes. 2472 */ 2473 usort( $this->lexical_updates, array( self::class, 'sort_start_ascending' ) ); 2474 2475 $bytes_already_copied = 0; 2476 $output_buffer = ''; 2477 foreach ( $this->lexical_updates as $diff ) { 2478 $shift = strlen( $diff->text ) - $diff->length; 2479 2480 // Adjust the cursor position by however much an update affects it. 2481 if ( $diff->start < $this->bytes_already_parsed ) { 2482 $this->bytes_already_parsed += $shift; 2483 } 2484 2485 // Accumulate shift of the given pointer within this function call. 2486 if ( $diff->start < $shift_this_point ) { 2487 $accumulated_shift_for_given_point += $shift; 2488 } 2489 2490 $output_buffer .= substr( $this->html, $bytes_already_copied, $diff->start - $bytes_already_copied ); 2491 $output_buffer .= $diff->text; 2492 $bytes_already_copied = $diff->start + $diff->length; 2493 } 2494 2495 $this->html = $output_buffer . substr( $this->html, $bytes_already_copied ); 2496 2497 /* 2498 * Adjust bookmark locations to account for how the text 2499 * replacements adjust offsets in the input document. 2500 */ 2501 foreach ( $this->bookmarks as $bookmark_name => $bookmark ) { 2502 $bookmark_end = $bookmark->start + $bookmark->length; 2503 2504 /* 2505 * Each lexical update which appears before the bookmark's endpoints 2506 * might shift the offsets for those endpoints. Loop through each change 2507 * and accumulate the total shift for each bookmark, then apply that 2508 * shift after tallying the full delta. 2509 */ 2510 $head_delta = 0; 2511 $tail_delta = 0; 2512 2513 foreach ( $this->lexical_updates as $diff ) { 2514 $diff_end = $diff->start + $diff->length; 2515 2516 if ( $bookmark->start < $diff->start && $bookmark_end < $diff->start ) { 2517 break; 2518 } 2519 2520 if ( $bookmark->start >= $diff->start && $bookmark_end < $diff_end ) { 2521 $this->release_bookmark( $bookmark_name ); 2522 continue 2; 2523 } 2524 2525 $delta = strlen( $diff->text ) - $diff->length; 2526 2527 if ( $bookmark->start >= $diff->start ) { 2528 $head_delta += $delta; 2529 } 2530 2531 if ( $bookmark_end >= $diff_end ) { 2532 $tail_delta += $delta; 2533 } 2534 } 2535 2536 $bookmark->start += $head_delta; 2537 $bookmark->length += $tail_delta - $head_delta; 2538 } 2539 2540 $this->lexical_updates = array(); 2541 2542 return $accumulated_shift_for_given_point; 2543 } 2544 2545 /** 2546 * Checks whether a bookmark with the given name exists. 2547 * 2548 * @since 6.3.0 2549 * 2550 * @param string $bookmark_name Name to identify a bookmark that potentially exists. 2551 * @return bool Whether that bookmark exists. 2552 */ 2553 public function has_bookmark( $bookmark_name ): bool { 2554 return array_key_exists( $bookmark_name, $this->bookmarks ); 2555 } 2556 2557 /** 2558 * Move the internal cursor in the Tag Processor to a given bookmark's location. 2559 * 2560 * In order to prevent accidental infinite loops, there's a 2561 * maximum limit on the number of times seek() can be called. 2562 * 2563 * @since 6.2.0 2564 * 2565 * @param string $bookmark_name Jump to the place in the document identified by this bookmark name. 2566 * @return bool Whether the internal cursor was successfully moved to the bookmark's location. 2567 */ 2568 public function seek( $bookmark_name ): bool { 2569 if ( ! array_key_exists( $bookmark_name, $this->bookmarks ) ) { 2570 _doing_it_wrong( 2571 __METHOD__, 2572 __( 'Unknown bookmark name.' ), 2573 '6.2.0' 2574 ); 2575 return false; 2576 } 2577 2578 $existing_bookmark = $this->bookmarks[ $bookmark_name ]; 2579 2580 if ( 2581 $this->token_starts_at === $existing_bookmark->start && 2582 $this->token_length === $existing_bookmark->length 2583 ) { 2584 return true; 2585 } 2586 2587 if ( ++$this->seek_count > static::MAX_SEEK_OPS ) { 2588 _doing_it_wrong( 2589 __METHOD__, 2590 __( 'Too many calls to seek() - this can lead to performance issues.' ), 2591 '6.2.0' 2592 ); 2593 return false; 2594 } 2595 2596 // Flush out any pending updates to the document. 2597 $this->get_updated_html(); 2598 2599 // Point this tag processor before the sought tag opener and consume it. 2600 $this->bytes_already_parsed = $this->bookmarks[ $bookmark_name ]->start; 2601 $this->parser_state = self::STATE_READY; 2602 return $this->next_token(); 2603 } 2604 2605 /** 2606 * Compare two WP_HTML_Text_Replacement objects. 2607 * 2608 * @since 6.2.0 2609 * 2610 * @param WP_HTML_Text_Replacement $a First attribute update. 2611 * @param WP_HTML_Text_Replacement $b Second attribute update. 2612 * @return int Comparison value for string order. 2613 */ 2614 private static function sort_start_ascending( WP_HTML_Text_Replacement $a, WP_HTML_Text_Replacement $b ): int { 2615 $by_start = $a->start - $b->start; 2616 if ( 0 !== $by_start ) { 2617 return $by_start; 2618 } 2619 2620 $by_text = isset( $a->text, $b->text ) ? strcmp( $a->text, $b->text ) : 0; 2621 if ( 0 !== $by_text ) { 2622 return $by_text; 2623 } 2624 2625 /* 2626 * This code should be unreachable, because it implies the two replacements 2627 * start at the same location and contain the same text. 2628 */ 2629 return $a->length - $b->length; 2630 } 2631 2632 /** 2633 * Return the enqueued value for a given attribute, if one exists. 2634 * 2635 * Enqueued updates can take different data types: 2636 * - If an update is enqueued and is boolean, the return will be `true` 2637 * - If an update is otherwise enqueued, the return will be the string value of that update. 2638 * - If an attribute is enqueued to be removed, the return will be `null` to indicate that. 2639 * - If no updates are enqueued, the return will be `false` to differentiate from "removed." 2640 * 2641 * @since 6.2.0 2642 * 2643 * @param string $comparable_name The attribute name in its comparable form. 2644 * @return string|boolean|null Value of enqueued update if present, otherwise false. 2645 */ 2646 private function get_enqueued_attribute_value( string $comparable_name ) { 2647 if ( self::STATE_MATCHED_TAG !== $this->parser_state ) { 2648 return false; 2649 } 2650 2651 if ( ! isset( $this->lexical_updates[ $comparable_name ] ) ) { 2652 return false; 2653 } 2654 2655 $enqueued_text = $this->lexical_updates[ $comparable_name ]->text; 2656 2657 // Removed attributes erase the entire span. 2658 if ( '' === $enqueued_text ) { 2659 return null; 2660 } 2661 2662 /* 2663 * Boolean attribute updates are just the attribute name without a corresponding value. 2664 * 2665 * This value might differ from the given comparable name in that there could be leading 2666 * or trailing whitespace, and that the casing follows the name given in `set_attribute`. 2667 * 2668 * Example: 2669 * 2670 * $p->set_attribute( 'data-TEST-id', 'update' ); 2671 * 'update' === $p->get_enqueued_attribute_value( 'data-test-id' ); 2672 * 2673 * Detect this difference based on the absence of the `=`, which _must_ exist in any 2674 * attribute containing a value, e.g. `<input type="text" enabled />`. 2675 * ¹ ² 2676 * 1. Attribute with a string value. 2677 * 2. Boolean attribute whose value is `true`. 2678 */ 2679 $equals_at = strpos( $enqueued_text, '=' ); 2680 if ( false === $equals_at ) { 2681 return true; 2682 } 2683 2684 /* 2685 * Finally, a normal update's value will appear after the `=` and 2686 * be double-quoted, as performed incidentally by `set_attribute`. 2687 * 2688 * e.g. `type="text"` 2689 * ¹² ³ 2690 * 1. Equals is here. 2691 * 2. Double-quoting starts one after the equals sign. 2692 * 3. Double-quoting ends at the last character in the update. 2693 */ 2694 $enqueued_value = substr( $enqueued_text, $equals_at + 2, -1 ); 2695 return WP_HTML_Decoder::decode_attribute( $enqueued_value ); 2696 } 2697 2698 /** 2699 * Returns the value of a requested attribute from a matched tag opener if that attribute exists. 2700 * 2701 * Example: 2702 * 2703 * $p = new WP_HTML_Tag_Processor( '<div enabled class="test" data-test-id="14">Test</div>' ); 2704 * $p->next_tag( array( 'class_name' => 'test' ) ) === true; 2705 * $p->get_attribute( 'data-test-id' ) === '14'; 2706 * $p->get_attribute( 'enabled' ) === true; 2707 * $p->get_attribute( 'aria-label' ) === null; 2708 * 2709 * $p->next_tag() === false; 2710 * $p->get_attribute( 'class' ) === null; 2711 * 2712 * @since 6.2.0 2713 * 2714 * @param string $name Name of attribute whose value is requested. 2715 * @return string|true|null Value of attribute or `null` if not available. Boolean attributes return `true`. 2716 */ 2717 public function get_attribute( $name ) { 2718 if ( self::STATE_MATCHED_TAG !== $this->parser_state ) { 2719 return null; 2720 } 2721 2722 $comparable = strtolower( $name ); 2723 2724 /* 2725 * For every attribute other than `class` it's possible to perform a quick check if 2726 * there's an enqueued lexical update whose value takes priority over what's found in 2727 * the input document. 2728 * 2729 * The `class` attribute is special though because of the exposed helpers `add_class` 2730 * and `remove_class`. These form a builder for the `class` attribute, so an additional 2731 * check for enqueued class changes is required in addition to the check for any enqueued 2732 * attribute values. If any exist, those enqueued class changes must first be flushed out 2733 * into an attribute value update. 2734 */ 2735 if ( 'class' === $name ) { 2736 $this->class_name_updates_to_attributes_updates(); 2737 } 2738 2739 // Return any enqueued attribute value updates if they exist. 2740 $enqueued_value = $this->get_enqueued_attribute_value( $comparable ); 2741 if ( false !== $enqueued_value ) { 2742 return $enqueued_value; 2743 } 2744 2745 if ( ! isset( $this->attributes[ $comparable ] ) ) { 2746 return null; 2747 } 2748 2749 $attribute = $this->attributes[ $comparable ]; 2750 2751 /* 2752 * This flag distinguishes an attribute with no value 2753 * from an attribute with an empty string value. For 2754 * unquoted attributes this could look very similar. 2755 * It refers to whether an `=` follows the name. 2756 * 2757 * e.g. <div boolean-attribute empty-attribute=></div> 2758 * ¹ ² 2759 * 1. Attribute `boolean-attribute` is `true`. 2760 * 2. Attribute `empty-attribute` is `""`. 2761 */ 2762 if ( true === $attribute->is_true ) { 2763 return true; 2764 } 2765 2766 $raw_value = substr( $this->html, $attribute->value_starts_at, $attribute->value_length ); 2767 2768 return WP_HTML_Decoder::decode_attribute( $raw_value ); 2769 } 2770 2771 /** 2772 * Gets lowercase names of all attributes matching a given prefix in the current tag. 2773 * 2774 * Note that matching is case-insensitive. This is in accordance with the spec: 2775 * 2776 * > There must never be two or more attributes on 2777 * > the same start tag whose names are an ASCII 2778 * > case-insensitive match for each other. 2779 * - HTML 5 spec 2780 * 2781 * Example: 2782 * 2783 * $p = new WP_HTML_Tag_Processor( '<div data-ENABLED class="test" DATA-test-id="14">Test</div>' ); 2784 * $p->next_tag( array( 'class_name' => 'test' ) ) === true; 2785 * $p->get_attribute_names_with_prefix( 'data-' ) === array( 'data-enabled', 'data-test-id' ); 2786 * 2787 * $p->next_tag() === false; 2788 * $p->get_attribute_names_with_prefix( 'data-' ) === null; 2789 * 2790 * @since 6.2.0 2791 * 2792 * @see https://html.spec.whatwg.org/multipage/syntax.html#attributes-2:ascii-case-insensitive 2793 * 2794 * @param string $prefix Prefix of requested attribute names. 2795 * @return array|null List of attribute names, or `null` when no tag opener is matched. 2796 */ 2797 public function get_attribute_names_with_prefix( $prefix ): ?array { 2798 if ( 2799 self::STATE_MATCHED_TAG !== $this->parser_state || 2800 $this->is_closing_tag 2801 ) { 2802 return null; 2803 } 2804 2805 $comparable = strtolower( $prefix ); 2806 2807 $matches = array(); 2808 foreach ( array_keys( $this->attributes ) as $attr_name ) { 2809 if ( str_starts_with( $attr_name, $comparable ) ) { 2810 $matches[] = $attr_name; 2811 } 2812 } 2813 return $matches; 2814 } 2815 2816 /** 2817 * Returns the namespace of the matched token. 2818 * 2819 * @since 6.7.0 2820 * 2821 * @return string One of 'html', 'math', or 'svg'. 2822 */ 2823 public function get_namespace(): string { 2824 return $this->parsing_namespace; 2825 } 2826 2827 /** 2828 * Returns the uppercase name of the matched tag. 2829 * 2830 * Example: 2831 * 2832 * $p = new WP_HTML_Tag_Processor( '<div class="test">Test</div>' ); 2833 * $p->next_tag() === true; 2834 * $p->get_tag() === 'DIV'; 2835 * 2836 * $p->next_tag() === false; 2837 * $p->get_tag() === null; 2838 * 2839 * @since 6.2.0 2840 * 2841 * @return string|null Name of currently matched tag in input HTML, or `null` if none found. 2842 */ 2843 public function get_tag(): ?string { 2844 if ( null === $this->tag_name_starts_at ) { 2845 return null; 2846 } 2847 2848 $tag_name = substr( $this->html, $this->tag_name_starts_at, $this->tag_name_length ); 2849 2850 if ( self::STATE_MATCHED_TAG === $this->parser_state ) { 2851 return strtoupper( $tag_name ); 2852 } 2853 2854 if ( 2855 self::STATE_COMMENT === $this->parser_state && 2856 self::COMMENT_AS_PI_NODE_LOOKALIKE === $this->get_comment_type() 2857 ) { 2858 return $tag_name; 2859 } 2860 2861 return null; 2862 } 2863 2864 /** 2865 * Returns the adjusted tag name for a given token, taking into 2866 * account the current parsing context, whether HTML, SVG, or MathML. 2867 * 2868 * @since 6.7.0 2869 * 2870 * @return string|null Name of current tag name. 2871 */ 2872 public function get_qualified_tag_name(): ?string { 2873 $tag_name = $this->get_tag(); 2874 if ( null === $tag_name ) { 2875 return null; 2876 } 2877 2878 if ( 'html' === $this->get_namespace() ) { 2879 return $tag_name; 2880 } 2881 2882 $lower_tag_name = strtolower( $tag_name ); 2883 if ( 'math' === $this->get_namespace() ) { 2884 return $lower_tag_name; 2885 } 2886 2887 if ( 'svg' === $this->get_namespace() ) { 2888 switch ( $lower_tag_name ) { 2889 case 'altglyph': 2890 return 'altGlyph'; 2891 2892 case 'altglyphdef': 2893 return 'altGlyphDef'; 2894 2895 case 'altglyphitem': 2896 return 'altGlyphItem'; 2897 2898 case 'animatecolor': 2899 return 'animateColor'; 2900 2901 case 'animatemotion': 2902 return 'animateMotion'; 2903 2904 case 'animatetransform': 2905 return 'animateTransform'; 2906 2907 case 'clippath': 2908 return 'clipPath'; 2909 2910 case 'feblend': 2911 return 'feBlend'; 2912 2913 case 'fecolormatrix': 2914 return 'feColorMatrix'; 2915 2916 case 'fecomponenttransfer': 2917 return 'feComponentTransfer'; 2918 2919 case 'fecomposite': 2920 return 'feComposite'; 2921 2922 case 'feconvolvematrix': 2923 return 'feConvolveMatrix'; 2924 2925 case 'fediffuselighting': 2926 return 'feDiffuseLighting'; 2927 2928 case 'fedisplacementmap': 2929 return 'feDisplacementMap'; 2930 2931 case 'fedistantlight': 2932 return 'feDistantLight'; 2933 2934 case 'fedropshadow': 2935 return 'feDropShadow'; 2936 2937 case 'feflood': 2938 return 'feFlood'; 2939 2940 case 'fefunca': 2941 return 'feFuncA'; 2942 2943 case 'fefuncb': 2944 return 'feFuncB'; 2945 2946 case 'fefuncg': 2947 return 'feFuncG'; 2948 2949 case 'fefuncr': 2950 return 'feFuncR'; 2951 2952 case 'fegaussianblur': 2953 return 'feGaussianBlur'; 2954 2955 case 'feimage': 2956 return 'feImage'; 2957 2958 case 'femerge': 2959 return 'feMerge'; 2960 2961 case 'femergenode': 2962 return 'feMergeNode'; 2963 2964 case 'femorphology': 2965 return 'feMorphology'; 2966 2967 case 'feoffset': 2968 return 'feOffset'; 2969 2970 case 'fepointlight': 2971 return 'fePointLight'; 2972 2973 case 'fespecularlighting': 2974 return 'feSpecularLighting'; 2975 2976 case 'fespotlight': 2977 return 'feSpotLight'; 2978 2979 case 'fetile': 2980 return 'feTile'; 2981 2982 case 'feturbulence': 2983 return 'feTurbulence'; 2984 2985 case 'foreignobject': 2986 return 'foreignObject'; 2987 2988 case 'glyphref': 2989 return 'glyphRef'; 2990 2991 case 'lineargradient': 2992 return 'linearGradient'; 2993 2994 case 'radialgradient': 2995 return 'radialGradient'; 2996 2997 case 'textpath': 2998 return 'textPath'; 2999 3000 default: 3001 return $lower_tag_name; 3002 } 3003 } 3004 3005 // This unnecessary return prevents tools from inaccurately reporting type errors. 3006 return $tag_name; 3007 } 3008 3009 /** 3010 * Returns the adjusted attribute name for a given attribute, taking into 3011 * account the current parsing context, whether HTML, SVG, or MathML. 3012 * 3013 * @since 6.7.0 3014 * 3015 * @param string $attribute_name Which attribute to adjust. 3016 * 3017 * @return string|null 3018 */ 3019 public function get_qualified_attribute_name( $attribute_name ): ?string { 3020 if ( self::STATE_MATCHED_TAG !== $this->parser_state ) { 3021 return null; 3022 } 3023 3024 $namespace = $this->get_namespace(); 3025 $lower_name = strtolower( $attribute_name ); 3026 3027 if ( 'math' === $namespace && 'definitionurl' === $lower_name ) { 3028 return 'definitionURL'; 3029 } 3030 3031 if ( 'svg' === $this->get_namespace() ) { 3032 switch ( $lower_name ) { 3033 case 'attributename': 3034 return 'attributeName'; 3035 3036 case 'attributetype': 3037 return 'attributeType'; 3038 3039 case 'basefrequency': 3040 return 'baseFrequency'; 3041 3042 case 'baseprofile': 3043 return 'baseProfile'; 3044 3045 case 'calcmode': 3046 return 'calcMode'; 3047 3048 case 'clippathunits': 3049 return 'clipPathUnits'; 3050 3051 case 'diffuseconstant': 3052 return 'diffuseConstant'; 3053 3054 case 'edgemode': 3055 return 'edgeMode'; 3056 3057 case 'filterunits': 3058 return 'filterUnits'; 3059 3060 case 'glyphref': 3061 return 'glyphRef'; 3062 3063 case 'gradienttransform': 3064 return 'gradientTransform'; 3065 3066 case 'gradientunits': 3067 return 'gradientUnits'; 3068 3069 case 'kernelmatrix': 3070 return 'kernelMatrix'; 3071 3072 case 'kernelunitlength': 3073 return 'kernelUnitLength'; 3074 3075 case 'keypoints': 3076 return 'keyPoints'; 3077 3078 case 'keysplines': 3079 return 'keySplines'; 3080 3081 case 'keytimes': 3082 return 'keyTimes'; 3083 3084 case 'lengthadjust': 3085 return 'lengthAdjust'; 3086 3087 case 'limitingconeangle': 3088 return 'limitingConeAngle'; 3089 3090 case 'markerheight': 3091 return 'markerHeight'; 3092 3093 case 'markerunits': 3094 return 'markerUnits'; 3095 3096 case 'markerwidth': 3097 return 'markerWidth'; 3098 3099 case 'maskcontentunits': 3100 return 'maskContentUnits'; 3101 3102 case 'maskunits': 3103 return 'maskUnits'; 3104 3105 case 'numoctaves': 3106 return 'numOctaves'; 3107 3108 case 'pathlength': 3109 return 'pathLength'; 3110 3111 case 'patterncontentunits': 3112 return 'patternContentUnits'; 3113 3114 case 'patterntransform': 3115 return 'patternTransform'; 3116 3117 case 'patternunits': 3118 return 'patternUnits'; 3119 3120 case 'pointsatx': 3121 return 'pointsAtX'; 3122 3123 case 'pointsaty': 3124 return 'pointsAtY'; 3125 3126 case 'pointsatz': 3127 return 'pointsAtZ'; 3128 3129 case 'preservealpha': 3130 return 'preserveAlpha'; 3131 3132 case 'preserveaspectratio': 3133 return 'preserveAspectRatio'; 3134 3135 case 'primitiveunits': 3136 return 'primitiveUnits'; 3137 3138 case 'refx': 3139 return 'refX'; 3140 3141 case 'refy': 3142 return 'refY'; 3143 3144 case 'repeatcount': 3145 return 'repeatCount'; 3146 3147 case 'repeatdur': 3148 return 'repeatDur'; 3149 3150 case 'requiredextensions': 3151 return 'requiredExtensions'; 3152 3153 case 'requiredfeatures': 3154 return 'requiredFeatures'; 3155 3156 case 'specularconstant': 3157 return 'specularConstant'; 3158 3159 case 'specularexponent': 3160 return 'specularExponent'; 3161 3162 case 'spreadmethod': 3163 return 'spreadMethod'; 3164 3165 case 'startoffset': 3166 return 'startOffset'; 3167 3168 case 'stddeviation': 3169 return 'stdDeviation'; 3170 3171 case 'stitchtiles': 3172 return 'stitchTiles'; 3173 3174 case 'surfacescale': 3175 return 'surfaceScale'; 3176 3177 case 'systemlanguage': 3178 return 'systemLanguage'; 3179 3180 case 'tablevalues': 3181 return 'tableValues'; 3182 3183 case 'targetx': 3184 return 'targetX'; 3185 3186 case 'targety': 3187 return 'targetY'; 3188 3189 case 'textlength': 3190 return 'textLength'; 3191 3192 case 'viewbox': 3193 return 'viewBox'; 3194 3195 case 'viewtarget': 3196 return 'viewTarget'; 3197 3198 case 'xchannelselector': 3199 return 'xChannelSelector'; 3200 3201 case 'ychannelselector': 3202 return 'yChannelSelector'; 3203 3204 case 'zoomandpan': 3205 return 'zoomAndPan'; 3206 } 3207 } 3208 3209 if ( 'html' !== $namespace ) { 3210 switch ( $lower_name ) { 3211 case 'xlink:actuate': 3212 return 'xlink actuate'; 3213 3214 case 'xlink:arcrole': 3215 return 'xlink arcrole'; 3216 3217 case 'xlink:href': 3218 return 'xlink href'; 3219 3220 case 'xlink:role': 3221 return 'xlink role'; 3222 3223 case 'xlink:show': 3224 return 'xlink show'; 3225 3226 case 'xlink:title': 3227 return 'xlink title'; 3228 3229 case 'xlink:type': 3230 return 'xlink type'; 3231 3232 case 'xml:lang': 3233 return 'xml lang'; 3234 3235 case 'xml:space': 3236 return 'xml space'; 3237 3238 case 'xmlns': 3239 return 'xmlns'; 3240 3241 case 'xmlns:xlink': 3242 return 'xmlns xlink'; 3243 } 3244 } 3245 3246 return $attribute_name; 3247 } 3248 3249 /** 3250 * Indicates if the currently matched tag contains the self-closing flag. 3251 * 3252 * No HTML elements ought to have the self-closing flag and for those, the self-closing 3253 * flag will be ignored. For void elements this is benign because they "self close" 3254 * automatically. For non-void HTML elements though problems will appear if someone 3255 * intends to use a self-closing element in place of that element with an empty body. 3256 * For HTML foreign elements and custom elements the self-closing flag determines if 3257 * they self-close or not. 3258 * 3259 * This function does not determine if a tag is self-closing, 3260 * but only if the self-closing flag is present in the syntax. 3261 * 3262 * @since 6.3.0 3263 * 3264 * @return bool Whether the currently matched tag contains the self-closing flag. 3265 */ 3266 public function has_self_closing_flag(): bool { 3267 if ( self::STATE_MATCHED_TAG !== $this->parser_state ) { 3268 return false; 3269 } 3270 3271 /* 3272 * The self-closing flag is the solidus at the _end_ of the tag, not the beginning. 3273 * 3274 * Example: 3275 * 3276 * <figure /> 3277 * ^ this appears one character before the end of the closing ">". 3278 */ 3279 return '/' === $this->html[ $this->token_starts_at + $this->token_length - 2 ]; 3280 } 3281 3282 /** 3283 * Indicates if the current tag token is a tag closer. 3284 * 3285 * Example: 3286 * 3287 * $p = new WP_HTML_Tag_Processor( '<div></div>' ); 3288 * $p->next_tag( array( 'tag_name' => 'div', 'tag_closers' => 'visit' ) ); 3289 * $p->is_tag_closer() === false; 3290 * 3291 * $p->next_tag( array( 'tag_name' => 'div', 'tag_closers' => 'visit' ) ); 3292 * $p->is_tag_closer() === true; 3293 * 3294 * @since 6.2.0 3295 * @since 6.7.0 Reports all BR tags as opening tags. 3296 * 3297 * @return bool Whether the current tag is a tag closer. 3298 */ 3299 public function is_tag_closer(): bool { 3300 return ( 3301 self::STATE_MATCHED_TAG === $this->parser_state && 3302 $this->is_closing_tag && 3303 3304 /* 3305 * The BR tag can only exist as an opening tag. If something like `</br>` 3306 * appears then the HTML parser will treat it as an opening tag with no 3307 * attributes. The BR tag is unique in this way. 3308 * 3309 * @see https://html.spec.whatwg.org/#parsing-main-inbody 3310 */ 3311 'BR' !== $this->get_tag() 3312 ); 3313 } 3314 3315 /** 3316 * Indicates the kind of matched token, if any. 3317 * 3318 * This differs from `get_token_name()` in that it always 3319 * returns a static string indicating the type, whereas 3320 * `get_token_name()` may return values derived from the 3321 * token itself, such as a tag name or processing 3322 * instruction tag. 3323 * 3324 * Possible values: 3325 * - `#tag` when matched on a tag. 3326 * - `#text` when matched on a text node. 3327 * - `#cdata-section` when matched on a CDATA node. 3328 * - `#comment` when matched on a comment. 3329 * - `#doctype` when matched on a DOCTYPE declaration. 3330 * - `#presumptuous-tag` when matched on an empty tag closer. 3331 * - `#funky-comment` when matched on a funky comment. 3332 * 3333 * @since 6.5.0 3334 * 3335 * @return string|null What kind of token is matched, or null. 3336 */ 3337 public function get_token_type(): ?string { 3338 switch ( $this->parser_state ) { 3339 case self::STATE_MATCHED_TAG: 3340 return '#tag'; 3341 3342 case self::STATE_DOCTYPE: 3343 return '#doctype'; 3344 3345 default: 3346 return $this->get_token_name(); 3347 } 3348 } 3349 3350 /** 3351 * Returns the node name represented by the token. 3352 * 3353 * This matches the DOM API value `nodeName`. Some values 3354 * are static, such as `#text` for a text node, while others 3355 * are dynamically generated from the token itself. 3356 * 3357 * Dynamic names: 3358 * - Uppercase tag name for tag matches. 3359 * - `html` for DOCTYPE declarations. 3360 * 3361 * Note that if the Tag Processor is not matched on a token 3362 * then this function will return `null`, either because it 3363 * hasn't yet found a token or because it reached the end 3364 * of the document without matching a token. 3365 * 3366 * @since 6.5.0 3367 * 3368 * @return string|null Name of the matched token. 3369 */ 3370 public function get_token_name(): ?string { 3371 switch ( $this->parser_state ) { 3372 case self::STATE_MATCHED_TAG: 3373 return $this->get_tag(); 3374 3375 case self::STATE_TEXT_NODE: 3376 return '#text'; 3377 3378 case self::STATE_CDATA_NODE: 3379 return '#cdata-section'; 3380 3381 case self::STATE_COMMENT: 3382 return '#comment'; 3383 3384 case self::STATE_DOCTYPE: 3385 return 'html'; 3386 3387 case self::STATE_PRESUMPTUOUS_TAG: 3388 return '#presumptuous-tag'; 3389 3390 case self::STATE_FUNKY_COMMENT: 3391 return '#funky-comment'; 3392 } 3393 3394 return null; 3395 } 3396 3397 /** 3398 * Indicates what kind of comment produced the comment node. 3399 * 3400 * Because there are different kinds of HTML syntax which produce 3401 * comments, the Tag Processor tracks and exposes this as a type 3402 * for the comment. Nominally only regular HTML comments exist as 3403 * they are commonly known, but a number of unrelated syntax errors 3404 * also produce comments. 3405 * 3406 * @see self::COMMENT_AS_ABRUPTLY_CLOSED_COMMENT 3407 * @see self::COMMENT_AS_CDATA_LOOKALIKE 3408 * @see self::COMMENT_AS_INVALID_HTML 3409 * @see self::COMMENT_AS_HTML_COMMENT 3410 * @see self::COMMENT_AS_PI_NODE_LOOKALIKE 3411 * 3412 * @since 6.5.0 3413 * 3414 * @return string|null 3415 */ 3416 public function get_comment_type(): ?string { 3417 if ( self::STATE_COMMENT !== $this->parser_state ) { 3418 return null; 3419 } 3420 3421 return $this->comment_type; 3422 } 3423 3424 /** 3425 * Returns the text of a matched comment or null if not on a comment type node. 3426 * 3427 * This method returns the entire text content of a comment node as it 3428 * would appear in the browser. 3429 * 3430 * This differs from {@see ::get_modifiable_text()} in that certain comment 3431 * types in the HTML API cannot allow their entire comment text content to 3432 * be modified. Namely, "bogus comments" of the form `<?not allowed in html>` 3433 * will create a comment whose text content starts with `?`. Note that if 3434 * that character were modified, it would be possible to change the node 3435 * type. 3436 * 3437 * @since 6.7.0 3438 * 3439 * @return string|null The comment text as it would appear in the browser or null 3440 * if not on a comment type node. 3441 */ 3442 public function get_full_comment_text(): ?string { 3443 if ( self::STATE_FUNKY_COMMENT === $this->parser_state ) { 3444 return $this->get_modifiable_text(); 3445 } 3446 3447 if ( self::STATE_COMMENT !== $this->parser_state ) { 3448 return null; 3449 } 3450 3451 switch ( $this->get_comment_type() ) { 3452 case self::COMMENT_AS_HTML_COMMENT: 3453 case self::COMMENT_AS_ABRUPTLY_CLOSED_COMMENT: 3454 return $this->get_modifiable_text(); 3455 3456 case self::COMMENT_AS_CDATA_LOOKALIKE: 3457 return "[CDATA[{$this->get_modifiable_text()}]]"; 3458 3459 case self::COMMENT_AS_PI_NODE_LOOKALIKE: 3460 return "?{$this->get_tag()}{$this->get_modifiable_text()}?"; 3461 3462 /* 3463 * This represents "bogus comments state" from HTML tokenization. 3464 * This can be entered by `<?` or `<!`, where `?` is included in 3465 * the comment text but `!` is not. 3466 */ 3467 case self::COMMENT_AS_INVALID_HTML: 3468 $preceding_character = $this->html[ $this->text_starts_at - 1 ]; 3469 $comment_start = '?' === $preceding_character ? '?' : ''; 3470 return "{$comment_start}{$this->get_modifiable_text()}"; 3471 } 3472 3473 return null; 3474 } 3475 3476 /** 3477 * Subdivides a matched text node, splitting NULL byte sequences and decoded whitespace as 3478 * distinct nodes prefixes. 3479 * 3480 * Note that once anything that's neither a NULL byte nor decoded whitespace is 3481 * encountered, then the remainder of the text node is left intact as generic text. 3482 * 3483 * - The HTML Processor uses this to apply distinct rules for different kinds of text. 3484 * - Inter-element whitespace can be detected and skipped with this method. 3485 * 3486 * Text nodes aren't eagerly subdivided because there's no need to split them unless 3487 * decisions are being made on NULL byte sequences or whitespace-only text. 3488 * 3489 * Example: 3490 * 3491 * $processor = new WP_HTML_Tag_Processor( "\x00Apples & Oranges" ); 3492 * true === $processor->next_token(); // Text is "Apples & Oranges". 3493 * true === $processor->subdivide_text_appropriately(); // Text is "". 3494 * true === $processor->next_token(); // Text is "Apples & Oranges". 3495 * false === $processor->subdivide_text_appropriately(); 3496 * 3497 * $processor = new WP_HTML_Tag_Processor( " \r\n\tMore" ); 3498 * true === $processor->next_token(); // Text is " ␉More". 3499 * true === $processor->subdivide_text_appropriately(); // Text is " ␉". 3500 * true === $processor->next_token(); // Text is "More". 3501 * false === $processor->subdivide_text_appropriately(); 3502 * 3503 * @since 6.7.0 3504 * 3505 * @return bool Whether the text node was subdivided. 3506 */ 3507 public function subdivide_text_appropriately(): bool { 3508 if ( self::STATE_TEXT_NODE !== $this->parser_state ) { 3509 return false; 3510 } 3511 3512 $this->text_node_classification = self::TEXT_IS_GENERIC; 3513 3514 /* 3515 * NULL bytes are treated categorically different than numeric character 3516 * references whose number is zero. `�` is not the same as `"\x00"`. 3517 */ 3518 $leading_nulls = strspn( $this->html, "\x00", $this->text_starts_at, $this->text_length ); 3519 if ( $leading_nulls > 0 ) { 3520 $this->token_length = $leading_nulls; 3521 $this->text_length = $leading_nulls; 3522 $this->bytes_already_parsed = $this->token_starts_at + $leading_nulls; 3523 $this->text_node_classification = self::TEXT_IS_NULL_SEQUENCE; 3524 return true; 3525 } 3526 3527 /* 3528 * Start a decoding loop to determine the point at which the 3529 * text subdivides. This entails raw whitespace bytes and any 3530 * character reference that decodes to the same. 3531 */ 3532 $at = $this->text_starts_at; 3533 $end = $this->text_starts_at + $this->text_length; 3534 while ( $at < $end ) { 3535 $skipped = strspn( $this->html, " \t\f\r\n", $at, $end - $at ); 3536 $at += $skipped; 3537 3538 if ( $at < $end && '&' === $this->html[ $at ] ) { 3539 $matched_byte_length = null; 3540 $replacement = WP_HTML_Decoder::read_character_reference( 'data', $this->html, $at, $matched_byte_length ); 3541 if ( isset( $replacement ) && 1 === strspn( $replacement, " \t\f\r\n" ) ) { 3542 $at += $matched_byte_length; 3543 continue; 3544 } 3545 } 3546 3547 break; 3548 } 3549 3550 if ( $at > $this->text_starts_at ) { 3551 $new_length = $at - $this->text_starts_at; 3552 $this->text_length = $new_length; 3553 $this->token_length = $new_length; 3554 $this->bytes_already_parsed = $at; 3555 $this->text_node_classification = self::TEXT_IS_WHITESPACE; 3556 return true; 3557 } 3558 3559 return false; 3560 } 3561 3562 /** 3563 * Returns the modifiable text for a matched token, or an empty string. 3564 * 3565 * Modifiable text is text content that may be read and changed without 3566 * changing the HTML structure of the document around it. This includes 3567 * the contents of `#text` nodes in the HTML as well as the inner 3568 * contents of HTML comments, Processing Instructions, and others, even 3569 * though these nodes aren't part of a parsed DOM tree. They also contain 3570 * the contents of SCRIPT and STYLE tags, of TEXTAREA tags, and of any 3571 * other section in an HTML document which cannot contain HTML markup (DATA). 3572 * 3573 * If a token has no modifiable text then an empty string is returned to 3574 * avoid needless crashing or type errors. An empty string does not mean 3575 * that a token has modifiable text, and a token with modifiable text may 3576 * have an empty string (e.g. a comment with no contents). 3577 * 3578 * Limitations: 3579 * 3580 * - This function will not strip the leading newline appropriately 3581 * after seeking into a LISTING or PRE element. To ensure that the 3582 * newline is treated properly, seek to the LISTING or PRE opening 3583 * tag instead of to the first text node inside the element. 3584 * 3585 * @since 6.5.0 3586 * @since 6.7.0 Replaces NULL bytes (U+0000) and newlines appropriately. 3587 * 3588 * @return string 3589 */ 3590 public function get_modifiable_text(): string { 3591 $has_enqueued_update = isset( $this->lexical_updates['modifiable text'] ); 3592 3593 if ( ! $has_enqueued_update && ( null === $this->text_starts_at || 0 === $this->text_length ) ) { 3594 return ''; 3595 } 3596 3597 $text = $has_enqueued_update 3598 ? $this->lexical_updates['modifiable text']->text 3599 : substr( $this->html, $this->text_starts_at, $this->text_length ); 3600 3601 /* 3602 * Pre-processing the input stream would normally happen before 3603 * any parsing is done, but deferring it means it's possible to 3604 * skip in most cases. When getting the modifiable text, however 3605 * it's important to apply the pre-processing steps, which is 3606 * normalizing newlines. 3607 * 3608 * @see https://html.spec.whatwg.org/#preprocessing-the-input-stream 3609 * @see https://infra.spec.whatwg.org/#normalize-newlines 3610 */ 3611 $text = str_replace( "\r\n", "\n", $text ); 3612 $text = str_replace( "\r", "\n", $text ); 3613 3614 // Comment data is not decoded. 3615 if ( 3616 self::STATE_CDATA_NODE === $this->parser_state || 3617 self::STATE_COMMENT === $this->parser_state || 3618 self::STATE_DOCTYPE === $this->parser_state || 3619 self::STATE_FUNKY_COMMENT === $this->parser_state 3620 ) { 3621 return str_replace( "\x00", "\u{FFFD}", $text ); 3622 } 3623 3624 $tag_name = $this->get_token_name(); 3625 if ( 3626 // Script data is not decoded. 3627 'SCRIPT' === $tag_name || 3628 3629 // RAWTEXT data is not decoded. 3630 'IFRAME' === $tag_name || 3631 'NOEMBED' === $tag_name || 3632 'NOFRAMES' === $tag_name || 3633 'STYLE' === $tag_name || 3634 'XMP' === $tag_name 3635 ) { 3636 return str_replace( "\x00", "\u{FFFD}", $text ); 3637 } 3638 3639 $decoded = WP_HTML_Decoder::decode_text_node( $text ); 3640 3641 /* 3642 * Skip the first line feed after LISTING, PRE, and TEXTAREA opening tags. 3643 * 3644 * Note that this first newline may come in the form of a character 3645 * reference, such as `
`, and so it's important to perform 3646 * this transformation only after decoding the raw text content. 3647 */ 3648 if ( 3649 ( "\n" === ( $decoded[0] ?? '' ) ) && 3650 ( ( $this->skip_newline_at === $this->token_starts_at && '#text' === $tag_name ) || 'TEXTAREA' === $tag_name ) 3651 ) { 3652 $decoded = substr( $decoded, 1 ); 3653 } 3654 3655 /* 3656 * Only in normative text nodes does the NULL byte (U+0000) get removed. 3657 * In all other contexts it's replaced by the replacement character (U+FFFD) 3658 * for security reasons (to avoid joining together strings that were safe 3659 * when separated, but not when joined). 3660 * 3661 * @todo Inside HTML integration points and MathML integration points, the 3662 * text is processed according to the insertion mode, not according 3663 * to the foreign content rules. This should strip the NULL bytes. 3664 */ 3665 return ( '#text' === $tag_name && 'html' === $this->get_namespace() ) 3666 ? str_replace( "\x00", '', $decoded ) 3667 : str_replace( "\x00", "\u{FFFD}", $decoded ); 3668 } 3669 3670 /** 3671 * Sets the modifiable text for the matched token, if matched. 3672 * 3673 * Modifiable text is text content that may be read and changed without 3674 * changing the HTML structure of the document around it. This includes 3675 * the contents of `#text` nodes in the HTML as well as the inner 3676 * contents of HTML comments, Processing Instructions, and others, even 3677 * though these nodes aren't part of a parsed DOM tree. They also contain 3678 * the contents of SCRIPT and STYLE tags, of TEXTAREA tags, and of any 3679 * other section in an HTML document which cannot contain HTML markup (DATA). 3680 * 3681 * Not all modifiable text may be set by this method, and not all content 3682 * may be set as modifiable text. In the case that this fails it will return 3683 * `false` indicating as much. For instance, it will not allow inserting the 3684 * string `</script` into a SCRIPT element, because the rules for escaping 3685 * that safely are complicated. Similarly, it will not allow setting content 3686 * into a comment which would prematurely terminate the comment. 3687 * 3688 * Example: 3689 * 3690 * // Add a preface to all STYLE contents. 3691 * while ( $processor->next_tag( 'STYLE' ) ) { 3692 * $style = $processor->get_modifiable_text(); 3693 * $processor->set_modifiable_text( "// Made with love on the World Wide Web\n{$style}" ); 3694 * } 3695 * 3696 * // Replace smiley text with Emoji smilies. 3697 * while ( $processor->next_token() ) { 3698 * if ( '#text' !== $processor->get_token_name() ) { 3699 * continue; 3700 * } 3701 * 3702 * $chunk = $processor->get_modifiable_text(); 3703 * if ( ! str_contains( $chunk, ':)' ) ) { 3704 * continue; 3705 * } 3706 * 3707 * $processor->set_modifiable_text( str_replace( ':)', '🙂', $chunk ) ); 3708 * } 3709 * 3710 * @since 6.7.0 3711 * 3712 * @param string $plaintext_content New text content to represent in the matched token. 3713 * 3714 * @return bool Whether the text was able to update. 3715 */ 3716 public function set_modifiable_text( string $plaintext_content ): bool { 3717 if ( self::STATE_TEXT_NODE === $this->parser_state ) { 3718 $this->lexical_updates['modifiable text'] = new WP_HTML_Text_Replacement( 3719 $this->text_starts_at, 3720 $this->text_length, 3721 htmlspecialchars( $plaintext_content, ENT_QUOTES | ENT_HTML5 ) 3722 ); 3723 3724 return true; 3725 } 3726 3727 // Comment data is not encoded. 3728 if ( 3729 self::STATE_COMMENT === $this->parser_state && 3730 self::COMMENT_AS_HTML_COMMENT === $this->comment_type 3731 ) { 3732 // Check if the text could close the comment. 3733 if ( 1 === preg_match( '/--!?>/', $plaintext_content ) ) { 3734 return false; 3735 } 3736 3737 $this->lexical_updates['modifiable text'] = new WP_HTML_Text_Replacement( 3738 $this->text_starts_at, 3739 $this->text_length, 3740 $plaintext_content 3741 ); 3742 3743 return true; 3744 } 3745 3746 if ( self::STATE_MATCHED_TAG !== $this->parser_state ) { 3747 return false; 3748 } 3749 3750 switch ( $this->get_tag() ) { 3751 case 'SCRIPT': 3752 /* 3753 * This is over-protective, but ensures the update doesn't break 3754 * out of the SCRIPT element. A more thorough check would need to 3755 * ensure that the script closing tag doesn't exist, and isn't 3756 * also "hidden" inside the script double-escaped state. 3757 * 3758 * It may seem like replacing `</script` with `<\/script` would 3759 * properly escape these things, but this could mask regex patterns 3760 * that previously worked. Resolve this by not sending `</script` 3761 */ 3762 if ( false !== stripos( $plaintext_content, '</script' ) ) { 3763 return false; 3764 } 3765 3766 $this->lexical_updates['modifiable text'] = new WP_HTML_Text_Replacement( 3767 $this->text_starts_at, 3768 $this->text_length, 3769 $plaintext_content 3770 ); 3771 3772 return true; 3773 3774 case 'STYLE': 3775 $plaintext_content = preg_replace_callback( 3776 '~</(?P<TAG_NAME>style)~i', 3777 static function ( $tag_match ) { 3778 return "\\3c\\2f{$tag_match['TAG_NAME']}"; 3779 }, 3780 $plaintext_content 3781 ); 3782 3783 $this->lexical_updates['modifiable text'] = new WP_HTML_Text_Replacement( 3784 $this->text_starts_at, 3785 $this->text_length, 3786 $plaintext_content 3787 ); 3788 3789 return true; 3790 3791 case 'TEXTAREA': 3792 case 'TITLE': 3793 $plaintext_content = preg_replace_callback( 3794 "~</(?P<TAG_NAME>{$this->get_tag()})~i", 3795 static function ( $tag_match ) { 3796 return "</{$tag_match['TAG_NAME']}"; 3797 }, 3798 $plaintext_content 3799 ); 3800 3801 /* 3802 * These don't _need_ to be escaped, but since they are decoded it's 3803 * safe to leave them escaped and this can prevent other code from 3804 * naively detecting tags within the contents. 3805 * 3806 * @todo It would be useful to prefix a multiline replacement text 3807 * with a newline, but not necessary. This is for aesthetics. 3808 */ 3809 $this->lexical_updates['modifiable text'] = new WP_HTML_Text_Replacement( 3810 $this->text_starts_at, 3811 $this->text_length, 3812 $plaintext_content 3813 ); 3814 3815 return true; 3816 } 3817 3818 return false; 3819 } 3820 3821 /** 3822 * Updates or creates a new attribute on the currently matched tag with the passed value. 3823 * 3824 * For boolean attributes special handling is provided: 3825 * - When `true` is passed as the value, then only the attribute name is added to the tag. 3826 * - When `false` is passed, the attribute gets removed if it existed before. 3827 * 3828 * For string attributes, the value is escaped using the `esc_attr` function. 3829 * 3830 * @since 6.2.0 3831 * @since 6.2.1 Fix: Only create a single update for multiple calls with case-variant attribute names. 3832 * 3833 * @param string $name The attribute name to target. 3834 * @param string|bool $value The new attribute value. 3835 * @return bool Whether an attribute value was set. 3836 */ 3837 public function set_attribute( $name, $value ): bool { 3838 if ( 3839 self::STATE_MATCHED_TAG !== $this->parser_state || 3840 $this->is_closing_tag 3841 ) { 3842 return false; 3843 } 3844 3845 /* 3846 * WordPress rejects more characters than are strictly forbidden 3847 * in HTML5. This is to prevent additional security risks deeper 3848 * in the WordPress and plugin stack. Specifically the 3849 * less-than (<) greater-than (>) and ampersand (&) aren't allowed. 3850 * 3851 * The use of a PCRE match enables looking for specific Unicode 3852 * code points without writing a UTF-8 decoder. Whereas scanning 3853 * for one-byte characters is trivial (with `strcspn`), scanning 3854 * for the longer byte sequences would be more complicated. Given 3855 * that this shouldn't be in the hot path for execution, it's a 3856 * reasonable compromise in efficiency without introducing a 3857 * noticeable impact on the overall system. 3858 * 3859 * @see https://html.spec.whatwg.org/#attributes-2 3860 * 3861 * @todo As the only regex pattern maybe we should take it out? 3862 * Are Unicode patterns available broadly in Core? 3863 */ 3864 if ( preg_match( 3865 '~[' . 3866 // Syntax-like characters. 3867 '"\'>&</ =' . 3868 // Control characters. 3869 '\x{00}-\x{1F}' . 3870 // HTML noncharacters. 3871 '\x{FDD0}-\x{FDEF}' . 3872 '\x{FFFE}\x{FFFF}\x{1FFFE}\x{1FFFF}\x{2FFFE}\x{2FFFF}\x{3FFFE}\x{3FFFF}' . 3873 '\x{4FFFE}\x{4FFFF}\x{5FFFE}\x{5FFFF}\x{6FFFE}\x{6FFFF}\x{7FFFE}\x{7FFFF}' . 3874 '\x{8FFFE}\x{8FFFF}\x{9FFFE}\x{9FFFF}\x{AFFFE}\x{AFFFF}\x{BFFFE}\x{BFFFF}' . 3875 '\x{CFFFE}\x{CFFFF}\x{DFFFE}\x{DFFFF}\x{EFFFE}\x{EFFFF}\x{FFFFE}\x{FFFFF}' . 3876 '\x{10FFFE}\x{10FFFF}' . 3877 ']~Ssu', 3878 $name 3879 ) ) { 3880 _doing_it_wrong( 3881 __METHOD__, 3882 __( 'Invalid attribute name.' ), 3883 '6.2.0' 3884 ); 3885 3886 return false; 3887 } 3888 3889 /* 3890 * > The values "true" and "false" are not allowed on boolean attributes. 3891 * > To represent a false value, the attribute has to be omitted altogether. 3892 * - HTML5 spec, https://html.spec.whatwg.org/#boolean-attributes 3893 */ 3894 if ( false === $value ) { 3895 return $this->remove_attribute( $name ); 3896 } 3897 3898 if ( true === $value ) { 3899 $updated_attribute = $name; 3900 } else { 3901 $comparable_name = strtolower( $name ); 3902 3903 /* 3904 * Escape URL attributes. 3905 * 3906 * @see https://html.spec.whatwg.org/#attributes-3 3907 */ 3908 $escaped_new_value = in_array( $comparable_name, wp_kses_uri_attributes(), true ) ? esc_url( $value ) : esc_attr( $value ); 3909 3910 // If the escaping functions wiped out the update, reject it and indicate it was rejected. 3911 if ( '' === $escaped_new_value && '' !== $value ) { 3912 return false; 3913 } 3914 3915 $updated_attribute = "{$name}=\"{$escaped_new_value}\""; 3916 } 3917 3918 /* 3919 * > There must never be two or more attributes on 3920 * > the same start tag whose names are an ASCII 3921 * > case-insensitive match for each other. 3922 * - HTML 5 spec 3923 * 3924 * @see https://html.spec.whatwg.org/multipage/syntax.html#attributes-2:ascii-case-insensitive 3925 */ 3926 $comparable_name = strtolower( $name ); 3927 3928 if ( isset( $this->attributes[ $comparable_name ] ) ) { 3929 /* 3930 * Update an existing attribute. 3931 * 3932 * Example – set attribute id to "new" in <div id="initial_id" />: 3933 * 3934 * <div id="initial_id"/> 3935 * ^-------------^ 3936 * start end 3937 * replacement: `id="new"` 3938 * 3939 * Result: <div id="new"/> 3940 */ 3941 $existing_attribute = $this->attributes[ $comparable_name ]; 3942 $this->lexical_updates[ $comparable_name ] = new WP_HTML_Text_Replacement( 3943 $existing_attribute->start, 3944 $existing_attribute->length, 3945 $updated_attribute 3946 ); 3947 } else { 3948 /* 3949 * Create a new attribute at the tag's name end. 3950 * 3951 * Example – add attribute id="new" to <div />: 3952 * 3953 * <div/> 3954 * ^ 3955 * start and end 3956 * replacement: ` id="new"` 3957 * 3958 * Result: <div id="new"/> 3959 */ 3960 $this->lexical_updates[ $comparable_name ] = new WP_HTML_Text_Replacement( 3961 $this->tag_name_starts_at + $this->tag_name_length, 3962 0, 3963 ' ' . $updated_attribute 3964 ); 3965 } 3966 3967 /* 3968 * Any calls to update the `class` attribute directly should wipe out any 3969 * enqueued class changes from `add_class` and `remove_class`. 3970 */ 3971 if ( 'class' === $comparable_name && ! empty( $this->classname_updates ) ) { 3972 $this->classname_updates = array(); 3973 } 3974 3975 return true; 3976 } 3977 3978 /** 3979 * Remove an attribute from the currently-matched tag. 3980 * 3981 * @since 6.2.0 3982 * 3983 * @param string $name The attribute name to remove. 3984 * @return bool Whether an attribute was removed. 3985 */ 3986 public function remove_attribute( $name ): bool { 3987 if ( 3988 self::STATE_MATCHED_TAG !== $this->parser_state || 3989 $this->is_closing_tag 3990 ) { 3991 return false; 3992 } 3993 3994 /* 3995 * > There must never be two or more attributes on 3996 * > the same start tag whose names are an ASCII 3997 * > case-insensitive match for each other. 3998 * - HTML 5 spec 3999 * 4000 * @see https://html.spec.whatwg.org/multipage/syntax.html#attributes-2:ascii-case-insensitive 4001 */ 4002 $name = strtolower( $name ); 4003 4004 /* 4005 * Any calls to update the `class` attribute directly should wipe out any 4006 * enqueued class changes from `add_class` and `remove_class`. 4007 */ 4008 if ( 'class' === $name && count( $this->classname_updates ) !== 0 ) { 4009 $this->classname_updates = array(); 4010 } 4011 4012 /* 4013 * If updating an attribute that didn't exist in the input 4014 * document, then remove the enqueued update and move on. 4015 * 4016 * For example, this might occur when calling `remove_attribute()` 4017 * after calling `set_attribute()` for the same attribute 4018 * and when that attribute wasn't originally present. 4019 */ 4020 if ( ! isset( $this->attributes[ $name ] ) ) { 4021 if ( isset( $this->lexical_updates[ $name ] ) ) { 4022 unset( $this->lexical_updates[ $name ] ); 4023 } 4024 return false; 4025 } 4026 4027 /* 4028 * Removes an existing tag attribute. 4029 * 4030 * Example – remove the attribute id from <div id="main"/>: 4031 * <div id="initial_id"/> 4032 * ^-------------^ 4033 * start end 4034 * replacement: `` 4035 * 4036 * Result: <div /> 4037 */ 4038 $this->lexical_updates[ $name ] = new WP_HTML_Text_Replacement( 4039 $this->attributes[ $name ]->start, 4040 $this->attributes[ $name ]->length, 4041 '' 4042 ); 4043 4044 // Removes any duplicated attributes if they were also present. 4045 foreach ( $this->duplicate_attributes[ $name ] ?? array() as $attribute_token ) { 4046 $this->lexical_updates[] = new WP_HTML_Text_Replacement( 4047 $attribute_token->start, 4048 $attribute_token->length, 4049 '' 4050 ); 4051 } 4052 4053 return true; 4054 } 4055 4056 /** 4057 * Adds a new class name to the currently matched tag. 4058 * 4059 * @since 6.2.0 4060 * 4061 * @param string $class_name The class name to add. 4062 * @return bool Whether the class was set to be added. 4063 */ 4064 public function add_class( $class_name ): bool { 4065 if ( 4066 self::STATE_MATCHED_TAG !== $this->parser_state || 4067 $this->is_closing_tag 4068 ) { 4069 return false; 4070 } 4071 4072 if ( self::QUIRKS_MODE !== $this->compat_mode ) { 4073 $this->classname_updates[ $class_name ] = self::ADD_CLASS; 4074 return true; 4075 } 4076 4077 /* 4078 * Because class names are matched ASCII-case-insensitively in quirks mode, 4079 * this needs to see if a case variant of the given class name is already 4080 * enqueued and update that existing entry, if so. This picks the casing of 4081 * the first-provided class name for all lexical variations. 4082 */ 4083 $class_name_length = strlen( $class_name ); 4084 foreach ( $this->classname_updates as $updated_name => $action ) { 4085 if ( 4086 strlen( $updated_name ) === $class_name_length && 4087 0 === substr_compare( $updated_name, $class_name, 0, $class_name_length, true ) 4088 ) { 4089 $this->classname_updates[ $updated_name ] = self::ADD_CLASS; 4090 return true; 4091 } 4092 } 4093 4094 $this->classname_updates[ $class_name ] = self::ADD_CLASS; 4095 return true; 4096 } 4097 4098 /** 4099 * Removes a class name from the currently matched tag. 4100 * 4101 * @since 6.2.0 4102 * 4103 * @param string $class_name The class name to remove. 4104 * @return bool Whether the class was set to be removed. 4105 */ 4106 public function remove_class( $class_name ): bool { 4107 if ( 4108 self::STATE_MATCHED_TAG !== $this->parser_state || 4109 $this->is_closing_tag 4110 ) { 4111 return false; 4112 } 4113 4114 if ( self::QUIRKS_MODE !== $this->compat_mode ) { 4115 $this->classname_updates[ $class_name ] = self::REMOVE_CLASS; 4116 return true; 4117 } 4118 4119 /* 4120 * Because class names are matched ASCII-case-insensitively in quirks mode, 4121 * this needs to see if a case variant of the given class name is already 4122 * enqueued and update that existing entry, if so. This picks the casing of 4123 * the first-provided class name for all lexical variations. 4124 */ 4125 $class_name_length = strlen( $class_name ); 4126 foreach ( $this->classname_updates as $updated_name => $action ) { 4127 if ( 4128 strlen( $updated_name ) === $class_name_length && 4129 0 === substr_compare( $updated_name, $class_name, 0, $class_name_length, true ) 4130 ) { 4131 $this->classname_updates[ $updated_name ] = self::REMOVE_CLASS; 4132 return true; 4133 } 4134 } 4135 4136 $this->classname_updates[ $class_name ] = self::REMOVE_CLASS; 4137 return true; 4138 } 4139 4140 /** 4141 * Returns the string representation of the HTML Tag Processor. 4142 * 4143 * @since 6.2.0 4144 * 4145 * @see WP_HTML_Tag_Processor::get_updated_html() 4146 * 4147 * @return string The processed HTML. 4148 */ 4149 public function __toString(): string { 4150 return $this->get_updated_html(); 4151 } 4152 4153 /** 4154 * Returns the string representation of the HTML Tag Processor. 4155 * 4156 * @since 6.2.0 4157 * @since 6.2.1 Shifts the internal cursor corresponding to the applied updates. 4158 * @since 6.4.0 No longer calls subclass method `next_tag()` after updating HTML. 4159 * 4160 * @return string The processed HTML. 4161 */ 4162 public function get_updated_html(): string { 4163 $requires_no_updating = 0 === count( $this->classname_updates ) && 0 === count( $this->lexical_updates ); 4164 4165 /* 4166 * When there is nothing more to update and nothing has already been 4167 * updated, return the original document and avoid a string copy. 4168 */ 4169 if ( $requires_no_updating ) { 4170 return $this->html; 4171 } 4172 4173 /* 4174 * Keep track of the position right before the current tag. This will 4175 * be necessary for reparsing the current tag after updating the HTML. 4176 */ 4177 $before_current_tag = $this->token_starts_at ?? 0; 4178 4179 /* 4180 * 1. Apply the enqueued edits and update all the pointers to reflect those changes. 4181 */ 4182 $this->class_name_updates_to_attributes_updates(); 4183 $before_current_tag += $this->apply_attributes_updates( $before_current_tag ); 4184 4185 /* 4186 * 2. Rewind to before the current tag and reparse to get updated attributes. 4187 * 4188 * At this point the internal cursor points to the end of the tag name. 4189 * Rewind before the tag name starts so that it's as if the cursor didn't 4190 * move; a call to `next_tag()` will reparse the recently-updated attributes 4191 * and additional calls to modify the attributes will apply at this same 4192 * location, but in order to avoid issues with subclasses that might add 4193 * behaviors to `next_tag()`, the internal methods should be called here 4194 * instead. 4195 * 4196 * It's important to note that in this specific place there will be no change 4197 * because the processor was already at a tag when this was called and it's 4198 * rewinding only to the beginning of this very tag before reprocessing it 4199 * and its attributes. 4200 * 4201 * <p>Previous HTML<em>More HTML</em></p> 4202 * ↑ │ back up by the length of the tag name plus the opening < 4203 * └←─┘ back up by strlen("em") + 1 ==> 3 4204 */ 4205 $this->bytes_already_parsed = $before_current_tag; 4206 $this->base_class_next_token(); 4207 4208 return $this->html; 4209 } 4210 4211 /** 4212 * Parses tag query input into internal search criteria. 4213 * 4214 * @since 6.2.0 4215 * 4216 * @param array|string|null $query { 4217 * Optional. Which tag name to find, having which class, etc. Default is to find any tag. 4218 * 4219 * @type string|null $tag_name Which tag to find, or `null` for "any tag." 4220 * @type int|null $match_offset Find the Nth tag matching all search criteria. 4221 * 1 for "first" tag, 3 for "third," etc. 4222 * Defaults to first tag. 4223 * @type string|null $class_name Tag must contain this class name to match. 4224 * @type string $tag_closers "visit" or "skip": whether to stop on tag closers, e.g. </div>. 4225 * } 4226 */ 4227 private function parse_query( $query ) { 4228 if ( null !== $query && $query === $this->last_query ) { 4229 return; 4230 } 4231 4232 $this->last_query = $query; 4233 $this->sought_tag_name = null; 4234 $this->sought_class_name = null; 4235 $this->sought_match_offset = 1; 4236 $this->stop_on_tag_closers = false; 4237 4238 // A single string value means "find the tag of this name". 4239 if ( is_string( $query ) ) { 4240 $this->sought_tag_name = $query; 4241 return; 4242 } 4243 4244 // An empty query parameter applies no restrictions on the search. 4245 if ( null === $query ) { 4246 return; 4247 } 4248 4249 // If not using the string interface, an associative array is required. 4250 if ( ! is_array( $query ) ) { 4251 _doing_it_wrong( 4252 __METHOD__, 4253 __( 'The query argument must be an array or a tag name.' ), 4254 '6.2.0' 4255 ); 4256 return; 4257 } 4258 4259 if ( isset( $query['tag_name'] ) && is_string( $query['tag_name'] ) ) { 4260 $this->sought_tag_name = $query['tag_name']; 4261 } 4262 4263 if ( isset( $query['class_name'] ) && is_string( $query['class_name'] ) ) { 4264 $this->sought_class_name = $query['class_name']; 4265 } 4266 4267 if ( isset( $query['match_offset'] ) && is_int( $query['match_offset'] ) && 0 < $query['match_offset'] ) { 4268 $this->sought_match_offset = $query['match_offset']; 4269 } 4270 4271 if ( isset( $query['tag_closers'] ) ) { 4272 $this->stop_on_tag_closers = 'visit' === $query['tag_closers']; 4273 } 4274 } 4275 4276 4277 /** 4278 * Checks whether a given tag and its attributes match the search criteria. 4279 * 4280 * @since 6.2.0 4281 * 4282 * @return bool Whether the given tag and its attribute match the search criteria. 4283 */ 4284 private function matches(): bool { 4285 if ( $this->is_closing_tag && ! $this->stop_on_tag_closers ) { 4286 return false; 4287 } 4288 4289 // Does the tag name match the requested tag name in a case-insensitive manner? 4290 if ( 4291 isset( $this->sought_tag_name ) && 4292 ( 4293 strlen( $this->sought_tag_name ) !== $this->tag_name_length || 4294 0 !== substr_compare( $this->html, $this->sought_tag_name, $this->tag_name_starts_at, $this->tag_name_length, true ) 4295 ) 4296 ) { 4297 return false; 4298 } 4299 4300 if ( null !== $this->sought_class_name && ! $this->has_class( $this->sought_class_name ) ) { 4301 return false; 4302 } 4303 4304 return true; 4305 } 4306 4307 /** 4308 * Gets DOCTYPE declaration info from a DOCTYPE token. 4309 * 4310 * DOCTYPE tokens may appear in many places in an HTML document. In most places, they are 4311 * simply ignored. The main parsing functions find the basic shape of DOCTYPE tokens but 4312 * do not perform detailed parsing. 4313 * 4314 * This method can be called to perform a full parse of the DOCTYPE token and retrieve 4315 * its information. 4316 * 4317 * @return WP_HTML_Doctype_Info|null The DOCTYPE declaration information or `null` if not 4318 * currently at a DOCTYPE node. 4319 */ 4320 public function get_doctype_info(): ?WP_HTML_Doctype_Info { 4321 if ( self::STATE_DOCTYPE !== $this->parser_state ) { 4322 return null; 4323 } 4324 4325 return WP_HTML_Doctype_Info::from_doctype_token( substr( $this->html, $this->token_starts_at, $this->token_length ) ); 4326 } 4327 4328 /** 4329 * Parser Ready State. 4330 * 4331 * Indicates that the parser is ready to run and waiting for a state transition. 4332 * It may not have started yet, or it may have just finished parsing a token and 4333 * is ready to find the next one. 4334 * 4335 * @since 6.5.0 4336 * 4337 * @access private 4338 */ 4339 const STATE_READY = 'STATE_READY'; 4340 4341 /** 4342 * Parser Complete State. 4343 * 4344 * Indicates that the parser has reached the end of the document and there is 4345 * nothing left to scan. It finished parsing the last token completely. 4346 * 4347 * @since 6.5.0 4348 * 4349 * @access private 4350 */ 4351 const STATE_COMPLETE = 'STATE_COMPLETE'; 4352 4353 /** 4354 * Parser Incomplete Input State. 4355 * 4356 * Indicates that the parser has reached the end of the document before finishing 4357 * a token. It started parsing a token but there is a possibility that the input 4358 * HTML document was truncated in the middle of a token. 4359 * 4360 * The parser is reset at the start of the incomplete token and has paused. There 4361 * is nothing more than can be scanned unless provided a more complete document. 4362 * 4363 * @since 6.5.0 4364 * 4365 * @access private 4366 */ 4367 const STATE_INCOMPLETE_INPUT = 'STATE_INCOMPLETE_INPUT'; 4368 4369 /** 4370 * Parser Matched Tag State. 4371 * 4372 * Indicates that the parser has found an HTML tag and it's possible to get 4373 * the tag name and read or modify its attributes (if it's not a closing tag). 4374 * 4375 * @since 6.5.0 4376 * 4377 * @access private 4378 */ 4379 const STATE_MATCHED_TAG = 'STATE_MATCHED_TAG'; 4380 4381 /** 4382 * Parser Text Node State. 4383 * 4384 * Indicates that the parser has found a text node and it's possible 4385 * to read and modify that text. 4386 * 4387 * @since 6.5.0 4388 * 4389 * @access private 4390 */ 4391 const STATE_TEXT_NODE = 'STATE_TEXT_NODE'; 4392 4393 /** 4394 * Parser CDATA Node State. 4395 * 4396 * Indicates that the parser has found a CDATA node and it's possible 4397 * to read and modify its modifiable text. Note that in HTML there are 4398 * no CDATA nodes outside of foreign content (SVG and MathML). Outside 4399 * of foreign content, they are treated as HTML comments. 4400 * 4401 * @since 6.5.0 4402 * 4403 * @access private 4404 */ 4405 const STATE_CDATA_NODE = 'STATE_CDATA_NODE'; 4406 4407 /** 4408 * Indicates that the parser has found an HTML comment and it's 4409 * possible to read and modify its modifiable text. 4410 * 4411 * @since 6.5.0 4412 * 4413 * @access private 4414 */ 4415 const STATE_COMMENT = 'STATE_COMMENT'; 4416 4417 /** 4418 * Indicates that the parser has found a DOCTYPE node and it's 4419 * possible to read its DOCTYPE information via `get_doctype_info()`. 4420 * 4421 * @since 6.5.0 4422 * 4423 * @access private 4424 */ 4425 const STATE_DOCTYPE = 'STATE_DOCTYPE'; 4426 4427 /** 4428 * Indicates that the parser has found an empty tag closer `</>`. 4429 * 4430 * Note that in HTML there are no empty tag closers, and they 4431 * are ignored. Nonetheless, the Tag Processor still 4432 * recognizes them as they appear in the HTML stream. 4433 * 4434 * These were historically discussed as a "presumptuous tag 4435 * closer," which would close the nearest open tag, but were 4436 * dismissed in favor of explicitly-closing tags. 4437 * 4438 * @since 6.5.0 4439 * 4440 * @access private 4441 */ 4442 const STATE_PRESUMPTUOUS_TAG = 'STATE_PRESUMPTUOUS_TAG'; 4443 4444 /** 4445 * Indicates that the parser has found a "funky comment" 4446 * and it's possible to read and modify its modifiable text. 4447 * 4448 * Example: 4449 * 4450 * </%url> 4451 * </{"wp-bit":"query/post-author"}> 4452 * </2> 4453 * 4454 * Funky comments are tag closers with invalid tag names. Note 4455 * that in HTML these are turn into bogus comments. Nonetheless, 4456 * the Tag Processor recognizes them in a stream of HTML and 4457 * exposes them for inspection and modification. 4458 * 4459 * @since 6.5.0 4460 * 4461 * @access private 4462 */ 4463 const STATE_FUNKY_COMMENT = 'STATE_WP_FUNKY'; 4464 4465 /** 4466 * Indicates that a comment was created when encountering abruptly-closed HTML comment. 4467 * 4468 * Example: 4469 * 4470 * <!--> 4471 * <!---> 4472 * 4473 * @since 6.5.0 4474 */ 4475 const COMMENT_AS_ABRUPTLY_CLOSED_COMMENT = 'COMMENT_AS_ABRUPTLY_CLOSED_COMMENT'; 4476 4477 /** 4478 * Indicates that a comment would be parsed as a CDATA node, 4479 * were HTML to allow CDATA nodes outside of foreign content. 4480 * 4481 * Example: 4482 * 4483 * <![CDATA[This is a CDATA node.]]> 4484 * 4485 * This is an HTML comment, but it looks like a CDATA node. 4486 * 4487 * @since 6.5.0 4488 */ 4489 const COMMENT_AS_CDATA_LOOKALIKE = 'COMMENT_AS_CDATA_LOOKALIKE'; 4490 4491 /** 4492 * Indicates that a comment was created when encountering 4493 * normative HTML comment syntax. 4494 * 4495 * Example: 4496 * 4497 * <!-- this is a comment --> 4498 * 4499 * @since 6.5.0 4500 */ 4501 const COMMENT_AS_HTML_COMMENT = 'COMMENT_AS_HTML_COMMENT'; 4502 4503 /** 4504 * Indicates that a comment would be parsed as a Processing 4505 * Instruction node, were they to exist within HTML. 4506 * 4507 * Example: 4508 * 4509 * <?wp __( 'Like' ) ?> 4510 * 4511 * This is an HTML comment, but it looks like a CDATA node. 4512 * 4513 * @since 6.5.0 4514 */ 4515 const COMMENT_AS_PI_NODE_LOOKALIKE = 'COMMENT_AS_PI_NODE_LOOKALIKE'; 4516 4517 /** 4518 * Indicates that a comment was created when encountering invalid 4519 * HTML input, a so-called "bogus comment." 4520 * 4521 * Example: 4522 * 4523 * <?nothing special> 4524 * <!{nothing special}> 4525 * 4526 * @since 6.5.0 4527 */ 4528 const COMMENT_AS_INVALID_HTML = 'COMMENT_AS_INVALID_HTML'; 4529 4530 /** 4531 * No-quirks mode document compatibility mode. 4532 * 4533 * > In no-quirks mode, the behavior is (hopefully) the desired behavior 4534 * > described by the modern HTML and CSS specifications. 4535 * 4536 * @see self::$compat_mode 4537 * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Quirks_Mode_and_Standards_Mode 4538 * 4539 * @since 6.7.0 4540 * 4541 * @var string 4542 */ 4543 const NO_QUIRKS_MODE = 'no-quirks-mode'; 4544 4545 /** 4546 * Quirks mode document compatibility mode. 4547 * 4548 * > In quirks mode, layout emulates behavior in Navigator 4 and Internet 4549 * > Explorer 5. This is essential in order to support websites that were 4550 * > built before the widespread adoption of web standards. 4551 * 4552 * @see self::$compat_mode 4553 * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Quirks_Mode_and_Standards_Mode 4554 * 4555 * @since 6.7.0 4556 * 4557 * @var string 4558 */ 4559 const QUIRKS_MODE = 'quirks-mode'; 4560 4561 /** 4562 * Indicates that a span of text may contain any combination of significant 4563 * kinds of characters: NULL bytes, whitespace, and others. 4564 * 4565 * @see self::$text_node_classification 4566 * @see self::subdivide_text_appropriately 4567 * 4568 * @since 6.7.0 4569 */ 4570 const TEXT_IS_GENERIC = 'TEXT_IS_GENERIC'; 4571 4572 /** 4573 * Indicates that a span of text comprises a sequence only of NULL bytes. 4574 * 4575 * @see self::$text_node_classification 4576 * @see self::subdivide_text_appropriately 4577 * 4578 * @since 6.7.0 4579 */ 4580 const TEXT_IS_NULL_SEQUENCE = 'TEXT_IS_NULL_SEQUENCE'; 4581 4582 /** 4583 * Indicates that a span of decoded text comprises only whitespace. 4584 * 4585 * @see self::$text_node_classification 4586 * @see self::subdivide_text_appropriately 4587 * 4588 * @since 6.7.0 4589 */ 4590 const TEXT_IS_WHITESPACE = 'TEXT_IS_WHITESPACE'; 4591 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated : Thu Aug 14 08:20:01 2025 | Cross-referenced by PHPXref |