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 */
12class 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_Decode::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_Decode::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|false Decoded character reference in UTF-8 if found, otherwise `false`.
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 ( false === $replacement ) {
365 return null;
366 }
367
368 $after_name = $name_at + $name_length;
369
370 // If the match ended with a semicolon then it should always be decoded.
371 if ( ';' === $text[ $name_at + $name_length - 1 ] ) {
372 $match_byte_length = $after_name - $at;
373 return $replacement;
374 }
375
376 /*
377 * At this point though there's a match for an entry in the named
378 * character reference table but the match doesn't end in `;`.
379 * It may be allowed if it's followed by something unambiguous.
380 */
381 $ambiguous_follower = (
382 $after_name < $length &&
383 $name_at < $length &&
384 (
385 ctype_alnum( $text[ $after_name ] ) ||
386 '=' === $text[ $after_name ]
387 )
388 );
389
390 // It's non-ambiguous, safe to leave it in.
391 if ( ! $ambiguous_follower ) {
392 $match_byte_length = $after_name - $at;
393 return $replacement;
394 }
395
396 // It's ambiguous, which isn't allowed inside attributes.
397 if ( 'attribute' === $context ) {
398 return null;
399 }
400
401 $match_byte_length = $after_name - $at;
402 return $replacement;
403 }
404
405 /**
406 * Encode a code point number into the UTF-8 encoding.
407 *
408 * This encoder implements the UTF-8 encoding algorithm for converting
409 * a code point into a byte sequence. If it receives an invalid code
410 * point it will return the Unicode Replacement Character U+FFFD `�`.
411 *
412 * Example:
413 *
414 * '🅰' === WP_HTML_Decoder::code_point_to_utf8_bytes( 0x1f170 );
415 *
416 * // Half of a surrogate pair is an invalid code point.
417 * '�' === WP_HTML_Decoder::code_point_to_utf8_bytes( 0xd83c );
418 *
419 * @since 6.6.0
420 *
421 * @see https://www.rfc-editor.org/rfc/rfc3629 For the UTF-8 standard.
422 *
423 * @param int $code_point Which code point to convert.
424 * @return string Converted code point, or `�` if invalid.
425 */
426 public static function code_point_to_utf8_bytes( $code_point ): string {
427 // Pre-check to ensure a valid code point.
428 if (
429 $code_point <= 0 ||
430 ( $code_point >= 0xD800 && $code_point <= 0xDFFF ) ||
431 $code_point > 0x10FFFF
432 ) {
433 return '�';
434 }
435
436 if ( $code_point <= 0x7F ) {
437 return chr( $code_point );
438 }
439
440 if ( $code_point <= 0x7FF ) {
441 $byte1 = chr( ( $code_point >> 6 ) | 0xC0 );
442 $byte2 = chr( $code_point & 0x3F | 0x80 );
443
444 return "{$byte1}{$byte2}";
445 }
446
447 if ( $code_point <= 0xFFFF ) {
448 $byte1 = chr( ( $code_point >> 12 ) | 0xE0 );
449 $byte2 = chr( ( $code_point >> 6 ) & 0x3F | 0x80 );
450 $byte3 = chr( $code_point & 0x3F | 0x80 );
451
452 return "{$byte1}{$byte2}{$byte3}";
453 }
454
455 // Any values above U+10FFFF are eliminated above in the pre-check.
456 $byte1 = chr( ( $code_point >> 18 ) | 0xF0 );
457 $byte2 = chr( ( $code_point >> 12 ) & 0x3F | 0x80 );
458 $byte3 = chr( ( $code_point >> 6 ) & 0x3F | 0x80 );
459 $byte4 = chr( $code_point & 0x3F | 0x80 );
460
461 return "{$byte1}{$byte2}{$byte3}{$byte4}";
462 }
463}
464