| [ Index ] |
PHP Cross Reference of WordPress Trunk (Updated Daily) |
[Summary view] [Print] [Text view]
1 <?php 2 3 /** 4 * HTML API: WP_HTML_Decoder class 5 * 6 * Decodes spans of raw text found inside HTML content. 7 * 8 * @package WordPress 9 * @subpackage HTML-API 10 * @since 6.6.0 11 */ 12 class WP_HTML_Decoder { 13 /** 14 * Indicates if an attribute value starts with a given raw string value. 15 * 16 * Use this method to determine if an attribute value starts with a given string, regardless 17 * of how it might be encoded in HTML. For instance, `http:` could be represented as `http:` 18 * or as `http:` or as `http:` or as `http:`, or in many other ways. 19 * 20 * Example: 21 * 22 * $value = 'http://wordpress.org/'; 23 * true === WP_HTML_Decoder::attribute_starts_with( $value, 'http:', 'ascii-case-insensitive' ); 24 * false === WP_HTML_Decoder::attribute_starts_with( $value, 'https:', 'ascii-case-insensitive' ); 25 * 26 * @since 6.6.0 27 * 28 * @param string $haystack String containing the raw non-decoded attribute value. 29 * @param string $search_text Does the attribute value start with this plain string. 30 * @param string $case_sensitivity Optional. Pass 'ascii-case-insensitive' to ignore ASCII case when matching. 31 * Default 'case-sensitive'. 32 * @return bool Whether the attribute value starts with the given string. 33 */ 34 public static function attribute_starts_with( $haystack, $search_text, $case_sensitivity = 'case-sensitive' ): bool { 35 $search_length = strlen( $search_text ); 36 $loose_case = 'ascii-case-insensitive' === $case_sensitivity; 37 $haystack_end = strlen( $haystack ); 38 $search_at = 0; 39 $haystack_at = 0; 40 41 while ( $search_at < $search_length && $haystack_at < $haystack_end ) { 42 $chars_match = $loose_case 43 ? strtolower( $haystack[ $haystack_at ] ) === strtolower( $search_text[ $search_at ] ) 44 : $haystack[ $haystack_at ] === $search_text[ $search_at ]; 45 46 $is_introducer = '&' === $haystack[ $haystack_at ]; 47 $next_chunk = $is_introducer 48 ? self::read_character_reference( 'attribute', $haystack, $haystack_at, $token_length ) 49 : null; 50 51 // If there's no character reference and the characters don't match, the match fails. 52 if ( null === $next_chunk && ! $chars_match ) { 53 return false; 54 } 55 56 // If there's no character reference but the character do match, then it could still match. 57 if ( null === $next_chunk && $chars_match ) { 58 ++$haystack_at; 59 ++$search_at; 60 continue; 61 } 62 63 // If there is a character reference, then the decoded value must exactly match what follows in the search string. 64 if ( 0 !== substr_compare( $search_text, $next_chunk, $search_at, strlen( $next_chunk ), $loose_case ) ) { 65 return false; 66 } 67 68 // The character reference matched, so continue checking. 69 $haystack_at += $token_length; 70 $search_at += strlen( $next_chunk ); 71 } 72 73 return true; 74 } 75 76 /** 77 * Returns a string containing the decoded value of a given HTML text node. 78 * 79 * Text nodes appear in HTML DATA sections, which are the text segments inside 80 * and around tags, excepting SCRIPT and STYLE elements (and some others), 81 * whose inner text is not decoded. Use this function to read the decoded 82 * value of such a text span in an HTML document. 83 * 84 * Example: 85 * 86 * '“😄”' === WP_HTML_Decoder::decode_text_node( '“😄”' ); 87 * 88 * @since 6.6.0 89 * 90 * @param string $text Text containing raw and non-decoded text node to decode. 91 * @return string Decoded UTF-8 value of given text node. 92 */ 93 public static function decode_text_node( $text ): string { 94 return static::decode( 'data', $text ); 95 } 96 97 /** 98 * Returns a string containing the decoded value of a given HTML attribute. 99 * 100 * Text found inside an HTML attribute has different parsing rules than for 101 * text found inside other markup, or DATA segments. Use this function to 102 * read the decoded value of an HTML string inside a quoted attribute. 103 * 104 * Example: 105 * 106 * '“😄”' === WP_HTML_Decoder::decode_attribute( '“😄”' ); 107 * 108 * @since 6.6.0 109 * 110 * @param string $text Text containing raw and non-decoded attribute value to decode. 111 * @return string Decoded UTF-8 value of given attribute value. 112 */ 113 public static function decode_attribute( $text ): string { 114 return static::decode( 'attribute', $text ); 115 } 116 117 /** 118 * Decodes a span of HTML text, depending on the context in which it's found. 119 * 120 * This is a low-level method; prefer calling WP_HTML_Decoder::decode_attribute() or 121 * WP_HTML_Decoder::decode_text_node() instead. It's provided for cases where this 122 * may be difficult to do from calling code. 123 * 124 * Example: 125 * 126 * '©' = WP_HTML_Decoder::decode( 'data', '©' ); 127 * 128 * @since 6.6.0 129 * 130 * @access private 131 * 132 * @param string $context `attribute` for decoding attribute values, `data` otherwise. 133 * @param string $text Text document containing span of text to decode. 134 * @return string Decoded UTF-8 string. 135 */ 136 public static function decode( $context, $text ): string { 137 $decoded = ''; 138 $end = strlen( $text ); 139 $at = 0; 140 $was_at = 0; 141 142 while ( $at < $end ) { 143 $next_character_reference_at = strpos( $text, '&', $at ); 144 if ( false === $next_character_reference_at ) { 145 break; 146 } 147 148 $character_reference = self::read_character_reference( $context, $text, $next_character_reference_at, $token_length ); 149 if ( isset( $character_reference ) ) { 150 $at = $next_character_reference_at; 151 $decoded .= substr( $text, $was_at, $at - $was_at ); 152 $decoded .= $character_reference; 153 $at += $token_length; 154 $was_at = $at; 155 continue; 156 } 157 158 ++$at; 159 } 160 161 if ( 0 === $was_at ) { 162 return $text; 163 } 164 165 if ( $was_at < $end ) { 166 $decoded .= substr( $text, $was_at, $end - $was_at ); 167 } 168 169 return $decoded; 170 } 171 172 /** 173 * Attempt to read a character reference at the given location in a given string, 174 * depending on the context in which it's found. 175 * 176 * If a character reference is found, this function will return the translated value 177 * that the reference maps to. It will then set `$match_byte_length` the 178 * number of bytes of input it read while consuming the character reference. This 179 * gives calling code the opportunity to advance its cursor when traversing a string 180 * and decoding. 181 * 182 * Example: 183 * 184 * null === WP_HTML_Decoder::read_character_reference( 'attribute', 'Ships…', 0 ); 185 * '…' === WP_HTML_Decoder::read_character_reference( 'attribute', 'Ships…', 5, $token_length ); 186 * 8 === $token_length; // `…` 187 * 188 * null === WP_HTML_Decoder::read_character_reference( 'attribute', '¬in', 0 ); 189 * '∉' === WP_HTML_Decoder::read_character_reference( 'attribute', '∉', 0, $token_length ); 190 * 7 === $token_length; // `∉` 191 * 192 * '¬' === WP_HTML_Decoder::read_character_reference( 'data', '¬in', 0, $token_length ); 193 * 4 === $token_length; // `¬` 194 * '∉' === WP_HTML_Decoder::read_character_reference( 'data', '∉', 0, $token_length ); 195 * 7 === $token_length; // `∉` 196 * 197 * @since 6.6.0 198 * 199 * @global WP_Token_Map $html5_named_character_references Mappings for HTML5 named character references. 200 * 201 * @param string $context `attribute` for decoding attribute values, `data` otherwise. 202 * @param string $text Text document containing span of text to decode. 203 * @param int $at Optional. Byte offset into text where span begins, defaults to the beginning (0). 204 * @param int &$match_byte_length Optional. Set to byte-length of character reference if provided and if a match 205 * is found, otherwise not set. Default null. 206 * @return ?string Decoded character reference in UTF-8 if found, otherwise null. 207 */ 208 public static function read_character_reference( $context, $text, $at = 0, &$match_byte_length = null ) { 209 /** 210 * Mappings for HTML5 named character references. 211 * 212 * @var WP_Token_Map $html5_named_character_references 213 */ 214 global $html5_named_character_references; 215 216 $length = strlen( $text ); 217 if ( $at + 1 >= $length ) { 218 return null; 219 } 220 221 if ( '&' !== $text[ $at ] ) { 222 return null; 223 } 224 225 /* 226 * Numeric character references. 227 * 228 * When truncated, these will encode the code point found by parsing the 229 * digits that are available. For example, when `🅰` is truncated 230 * to `DZ` it will encode `DZ`. It does not: 231 * - know how to parse the original `🅰`. 232 * - fail to parse and return plaintext `DZ`. 233 * - fail to parse and return the replacement character `�` 234 */ 235 if ( '#' === $text[ $at + 1 ] ) { 236 if ( $at + 2 >= $length ) { 237 return null; 238 } 239 240 /** Tracks inner parsing within the numeric character reference. */ 241 $digits_at = $at + 2; 242 243 if ( 'x' === $text[ $digits_at ] || 'X' === $text[ $digits_at ] ) { 244 $numeric_base = 16; 245 $numeric_digits = '0123456789abcdefABCDEF'; 246 $max_digits = 6; //  247 ++$digits_at; 248 } else { 249 $numeric_base = 10; 250 $numeric_digits = '0123456789'; 251 $max_digits = 7; //  252 } 253 254 // Cannot encode invalid Unicode code points. Max is to U+10FFFF. 255 $zero_count = strspn( $text, '0', $digits_at ); 256 $digit_count = strspn( $text, $numeric_digits, $digits_at + $zero_count ); 257 $after_digits = $digits_at + $zero_count + $digit_count; 258 $has_semicolon = $after_digits < $length && ';' === $text[ $after_digits ]; 259 $end_of_span = $has_semicolon ? $after_digits + 1 : $after_digits; 260 261 // `&#` or `&#x` without digits returns into plaintext. 262 if ( 0 === $digit_count && 0 === $zero_count ) { 263 return null; 264 } 265 266 // Whereas `&#` and only zeros is invalid. 267 if ( 0 === $digit_count ) { 268 $match_byte_length = $end_of_span - $at; 269 return '�'; 270 } 271 272 // If there are too many digits then it's not worth parsing. It's invalid. 273 if ( $digit_count > $max_digits ) { 274 $match_byte_length = $end_of_span - $at; 275 return '�'; 276 } 277 278 $digits = substr( $text, $digits_at + $zero_count, $digit_count ); 279 $code_point = intval( $digits, $numeric_base ); 280 281 /* 282 * Noncharacters, 0x0D, and non-ASCII-whitespace control characters. 283 * 284 * > A noncharacter is a code point that is in the range U+FDD0 to U+FDEF, 285 * > inclusive, or U+FFFE, U+FFFF, U+1FFFE, U+1FFFF, U+2FFFE, U+2FFFF, 286 * > U+3FFFE, U+3FFFF, U+4FFFE, U+4FFFF, U+5FFFE, U+5FFFF, U+6FFFE, 287 * > U+6FFFF, U+7FFFE, U+7FFFF, U+8FFFE, U+8FFFF, U+9FFFE, U+9FFFF, 288 * > U+AFFFE, U+AFFFF, U+BFFFE, U+BFFFF, U+CFFFE, U+CFFFF, U+DFFFE, 289 * > U+DFFFF, U+EFFFE, U+EFFFF, U+FFFFE, U+FFFFF, U+10FFFE, or U+10FFFF. 290 * 291 * A C0 control is a code point that is in the range of U+00 to U+1F, 292 * but ASCII whitespace includes U+09, U+0A, U+0C, and U+0D. 293 * 294 * These characters are invalid but still decode as any valid character. 295 * This comment is here to note and explain why there's no check to 296 * remove these characters or replace them. 297 * 298 * @see https://infra.spec.whatwg.org/#noncharacter 299 */ 300 301 /* 302 * Code points in the C1 controls area need to be remapped as if they 303 * were stored in Windows-1252. Note! This transformation only happens 304 * for numeric character references. The raw code points in the byte 305 * stream are not translated. 306 * 307 * > If the number is one of the numbers in the first column of 308 * > the following table, then find the row with that number in 309 * > the first column, and set the character reference code to 310 * > the number in the second column of that row. 311 */ 312 if ( $code_point >= 0x80 && $code_point <= 0x9F ) { 313 $windows_1252_mapping = array( 314 0x20AC, // 0x80 -> EURO SIGN (€). 315 0x81, // 0x81 -> (no change). 316 0x201A, // 0x82 -> SINGLE LOW-9 QUOTATION MARK (‚). 317 0x0192, // 0x83 -> LATIN SMALL LETTER F WITH HOOK (ƒ). 318 0x201E, // 0x84 -> DOUBLE LOW-9 QUOTATION MARK („). 319 0x2026, // 0x85 -> HORIZONTAL ELLIPSIS (…). 320 0x2020, // 0x86 -> DAGGER (†). 321 0x2021, // 0x87 -> DOUBLE DAGGER (‡). 322 0x02C6, // 0x88 -> MODIFIER LETTER CIRCUMFLEX ACCENT (ˆ). 323 0x2030, // 0x89 -> PER MILLE SIGN (‰). 324 0x0160, // 0x8A -> LATIN CAPITAL LETTER S WITH CARON (Š). 325 0x2039, // 0x8B -> SINGLE LEFT-POINTING ANGLE QUOTATION MARK (‹). 326 0x0152, // 0x8C -> LATIN CAPITAL LIGATURE OE (Œ). 327 0x8D, // 0x8D -> (no change). 328 0x017D, // 0x8E -> LATIN CAPITAL LETTER Z WITH CARON (Ž). 329 0x8F, // 0x8F -> (no change). 330 0x90, // 0x90 -> (no change). 331 0x2018, // 0x91 -> LEFT SINGLE QUOTATION MARK (‘). 332 0x2019, // 0x92 -> RIGHT SINGLE QUOTATION MARK (’). 333 0x201C, // 0x93 -> LEFT DOUBLE QUOTATION MARK (“). 334 0x201D, // 0x94 -> RIGHT DOUBLE QUOTATION MARK (”). 335 0x2022, // 0x95 -> BULLET (•). 336 0x2013, // 0x96 -> EN DASH (–). 337 0x2014, // 0x97 -> EM DASH (—). 338 0x02DC, // 0x98 -> SMALL TILDE (˜). 339 0x2122, // 0x99 -> TRADE MARK SIGN (™). 340 0x0161, // 0x9A -> LATIN SMALL LETTER S WITH CARON (š). 341 0x203A, // 0x9B -> SINGLE RIGHT-POINTING ANGLE QUOTATION MARK (›). 342 0x0153, // 0x9C -> LATIN SMALL LIGATURE OE (œ). 343 0x9D, // 0x9D -> (no change). 344 0x017E, // 0x9E -> LATIN SMALL LETTER Z WITH CARON (ž). 345 0x0178, // 0x9F -> LATIN CAPITAL LETTER Y WITH DIAERESIS (Ÿ). 346 ); 347 348 $code_point = $windows_1252_mapping[ $code_point - 0x80 ]; 349 } 350 351 $match_byte_length = $end_of_span - $at; 352 return self::code_point_to_utf8_bytes( $code_point ); 353 } 354 355 /** Tracks inner parsing within the named character reference. */ 356 $name_at = $at + 1; 357 // Minimum named character reference is two characters. E.g. `GT`. 358 if ( $name_at + 2 > $length ) { 359 return null; 360 } 361 362 $name_length = 0; 363 $replacement = $html5_named_character_references->read_token( $text, $name_at, $name_length ); 364 if ( null === $replacement ) { 365 return null; 366 } 367 368 $after_name = $name_at + $name_length; 369 370 /** 371 * For historical reasons, a matched named character reference is left as literal 372 * text (its decoded replacement is not used) when all of the following hold: 373 * 374 * 1. It was matched in attribute context. 375 * 2. The match does not end in U+003B SEMICOLON (;) — i.e. it is one of the 376 * legacy forms recognized without a trailing semicolon. 377 * 3. The next input character is U+003D EQUALS SIGN (=) or an ASCII alphanumeric. 378 * 379 * Some illustrative examples follow. Note that both `not` and `not;` appear in the 380 * named character references list. References start with `&` and typically end with 381 * `;`, but the legacy forms are recognized without one. 382 * 383 * - In _data context_, "¬me" is decoded to "¬me": condition 1 fails (not an 384 * attribute), so the reference is decoded. 385 * - In _attribute context_, "¬me" is decoded to "¬me": the longest match is 386 * "not;", which ends in a semicolon, so condition 2 fails. 387 * - In _attribute context_, "¬己" is decoded to "¬己": the following character 388 * "己" is a letter but not an ASCII alphanumeric (nor "="), so condition 3 fails. 389 * - In _attribute context_, "¬" is decoded to "¬": there is no next input 390 * character, so condition 3 fails. 391 * - In _attribute context_, "¬=me" is left as the literal text "¬=me": all 392 * three conditions hold. 393 * - In _attribute context_, "¬me" is left as the literal text "¬me": all 394 * three conditions hold. 395 * 396 * Without these special rules, ordinary URL query strings could have surprising 397 * replacements applied. Consider: 398 * 399 * <a href="/?random°ree>=0<=360¬=90"> 400 * 401 * The literal attribute value `/?random°ree>=0<=360¬=90` is preserved 402 * by the special handling. Otherwise, the value would decode to 403 * `/?random°ree>=0<=360¬=90`, which is unlikely to be the author's intent. 404 * 405 * (Authors should not rely on this. Escaping the example as 406 * `/?random&degree&gt=0&lt=360&not=90` produces the intended 407 * value regardless of the following character.) 408 * 409 * @see https://html.spec.whatwg.org/multipage/parsing.html#named-character-reference-state 410 * @see https://html.spec.whatwg.org/multipage/named-characters.html#named-character-references 411 */ 412 if ( 'attribute' !== $context || ';' === $text[ $after_name - 1 ] || $after_name >= $length ) { 413 $match_byte_length = $after_name - $at; 414 return $replacement; 415 } 416 417 $follower_byte = ord( $text[ $after_name ] ); 418 if ( 419 0x3D === $follower_byte || // EQUALS SIGN 420 ( $follower_byte >= 0x30 && $follower_byte <= 0x39 ) || // ASCII digits 0-9 421 ( $follower_byte >= 0x41 && $follower_byte <= 0x5A ) || // ASCII upper alpha A-Z 422 ( $follower_byte >= 0x61 && $follower_byte <= 0x7A ) // ASCII lower alpha a-z 423 ) { 424 return null; 425 } 426 427 $match_byte_length = $after_name - $at; 428 return $replacement; 429 } 430 431 /** 432 * Encode a code point number into the UTF-8 encoding. 433 * 434 * This encoder implements the UTF-8 encoding algorithm for converting 435 * a code point into a byte sequence. If it receives an invalid code 436 * point it will return the Unicode Replacement Character U+FFFD `�`. 437 * 438 * Example: 439 * 440 * '🅰' === WP_HTML_Decoder::code_point_to_utf8_bytes( 0x1f170 ); 441 * 442 * // Half of a surrogate pair is an invalid code point. 443 * '�' === WP_HTML_Decoder::code_point_to_utf8_bytes( 0xd83c ); 444 * 445 * @since 6.6.0 446 * 447 * @see https://www.rfc-editor.org/rfc/rfc3629 For the UTF-8 standard. 448 * 449 * @param int $code_point Which code point to convert. 450 * @return string Converted code point, or `�` if invalid. 451 */ 452 public static function code_point_to_utf8_bytes( $code_point ): string { 453 $string = mb_chr( $code_point, 'UTF-8' ); 454 455 return false !== $string ? $string : '�'; 456 } 457 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated : Sat Jul 4 08:20:12 2026 | Cross-referenced by PHPXref |