WP_HTML_Decoder::read_character_reference() │ public static │ WP 6.6.0
Attempt to read a character reference at the given location in a given string, depending on the context in which it's found.
If a character reference is found, this function will return the translated value that the reference maps to. It will then set $match_byte_length the number of bytes of input it read while consuming the character reference. This gives calling code the opportunity to advance its cursor when traversing a string and decoding.
public static function read_character_reference( $context, $text, $at = 0, &$match_byte_length = null ) {
/**
* Mappings for HTML5 named character references.
*
* @var WP_Token_Map $html5_named_character_references
*/
global $html5_named_character_references;
$length = strlen( $text );
if ( $at + 1 >= $length ) {
return null;
}
if ( '&' !== $text[ $at ] ) {
return null;
}
/*
* Numeric character references.
*
* When truncated, these will encode the code point found by parsing the
* digits that are available. For example, when `🅰` is truncated
* to `DZ` it will encode `DZ`. It does not:
* - know how to parse the original `🅰`.
* - fail to parse and return plaintext `DZ`.
* - fail to parse and return the replacement character `�`
*/
if ( '#' === $text[ $at + 1 ] ) {
if ( $at + 2 >= $length ) {
return null;
}
/** Tracks inner parsing within the numeric character reference. */
$digits_at = $at + 2;
if ( 'x' === $text[ $digits_at ] || 'X' === $text[ $digits_at ] ) {
$numeric_base = 16;
$numeric_digits = '0123456789abcdefABCDEF';
$max_digits = 6; // 
++$digits_at;
} else {
$numeric_base = 10;
$numeric_digits = '0123456789';
$max_digits = 7; // 
}
// Cannot encode invalid Unicode code points. Max is to U+10FFFF.
$zero_count = strspn( $text, '0', $digits_at );
$digit_count = strspn( $text, $numeric_digits, $digits_at + $zero_count );
$after_digits = $digits_at + $zero_count + $digit_count;
$has_semicolon = $after_digits < $length && ';' === $text[ $after_digits ];
$end_of_span = $has_semicolon ? $after_digits + 1 : $after_digits;
// `&#` or `&#x` without digits returns into plaintext.
if ( 0 === $digit_count && 0 === $zero_count ) {
return null;
}
// Whereas `&#` and only zeros is invalid.
if ( 0 === $digit_count ) {
$match_byte_length = $end_of_span - $at;
return '�';
}
// If there are too many digits then it's not worth parsing. It's invalid.
if ( $digit_count > $max_digits ) {
$match_byte_length = $end_of_span - $at;
return '�';
}
$digits = substr( $text, $digits_at + $zero_count, $digit_count );
$code_point = intval( $digits, $numeric_base );
/*
* Noncharacters, 0x0D, and non-ASCII-whitespace control characters.
*
* > A noncharacter is a code point that is in the range U+FDD0 to U+FDEF,
* > inclusive, or U+FFFE, U+FFFF, U+1FFFE, U+1FFFF, U+2FFFE, U+2FFFF,
* > U+3FFFE, U+3FFFF, U+4FFFE, U+4FFFF, U+5FFFE, U+5FFFF, U+6FFFE,
* > U+6FFFF, U+7FFFE, U+7FFFF, U+8FFFE, U+8FFFF, U+9FFFE, U+9FFFF,
* > U+AFFFE, U+AFFFF, U+BFFFE, U+BFFFF, U+CFFFE, U+CFFFF, U+DFFFE,
* > U+DFFFF, U+EFFFE, U+EFFFF, U+FFFFE, U+FFFFF, U+10FFFE, or U+10FFFF.
*
* A C0 control is a code point that is in the range of U+00 to U+1F,
* but ASCII whitespace includes U+09, U+0A, U+0C, and U+0D.
*
* These characters are invalid but still decode as any valid character.
* This comment is here to note and explain why there's no check to
* remove these characters or replace them.
*
* @see https://infra.spec.whatwg.org/#noncharacter
*/
/*
* Code points in the C1 controls area need to be remapped as if they
* were stored in Windows-1252. Note! This transformation only happens
* for numeric character references. The raw code points in the byte
* stream are not translated.
*
* > If the number is one of the numbers in the first column of
* > the following table, then find the row with that number in
* > the first column, and set the character reference code to
* > the number in the second column of that row.
*/
if ( $code_point >= 0x80 && $code_point <= 0x9F ) {
$windows_1252_mapping = array(
0x20AC, // 0x80 -> EURO SIGN (€).
0x81, // 0x81 -> (no change).
0x201A, // 0x82 -> SINGLE LOW-9 QUOTATION MARK (‚).
0x0192, // 0x83 -> LATIN SMALL LETTER F WITH HOOK (ƒ).
0x201E, // 0x84 -> DOUBLE LOW-9 QUOTATION MARK („).
0x2026, // 0x85 -> HORIZONTAL ELLIPSIS (…).
0x2020, // 0x86 -> DAGGER (†).
0x2021, // 0x87 -> DOUBLE DAGGER (‡).
0x02C6, // 0x88 -> MODIFIER LETTER CIRCUMFLEX ACCENT (ˆ).
0x2030, // 0x89 -> PER MILLE SIGN (‰).
0x0160, // 0x8A -> LATIN CAPITAL LETTER S WITH CARON (Š).
0x2039, // 0x8B -> SINGLE LEFT-POINTING ANGLE QUOTATION MARK (‹).
0x0152, // 0x8C -> LATIN CAPITAL LIGATURE OE (Œ).
0x8D, // 0x8D -> (no change).
0x017D, // 0x8E -> LATIN CAPITAL LETTER Z WITH CARON (Ž).
0x8F, // 0x8F -> (no change).
0x90, // 0x90 -> (no change).
0x2018, // 0x91 -> LEFT SINGLE QUOTATION MARK (‘).
0x2019, // 0x92 -> RIGHT SINGLE QUOTATION MARK (’).
0x201C, // 0x93 -> LEFT DOUBLE QUOTATION MARK (“).
0x201D, // 0x94 -> RIGHT DOUBLE QUOTATION MARK (”).
0x2022, // 0x95 -> BULLET (•).
0x2013, // 0x96 -> EN DASH (–).
0x2014, // 0x97 -> EM DASH (—).
0x02DC, // 0x98 -> SMALL TILDE (˜).
0x2122, // 0x99 -> TRADE MARK SIGN (™).
0x0161, // 0x9A -> LATIN SMALL LETTER S WITH CARON (š).
0x203A, // 0x9B -> SINGLE RIGHT-POINTING ANGLE QUOTATION MARK (›).
0x0153, // 0x9C -> LATIN SMALL LIGATURE OE (œ).
0x9D, // 0x9D -> (no change).
0x017E, // 0x9E -> LATIN SMALL LETTER Z WITH CARON (ž).
0x0178, // 0x9F -> LATIN CAPITAL LETTER Y WITH DIAERESIS (Ÿ).
);
$code_point = $windows_1252_mapping[ $code_point - 0x80 ];
}
$match_byte_length = $end_of_span - $at;
return self::code_point_to_utf8_bytes( $code_point );
}
/** Tracks inner parsing within the named character reference. */
$name_at = $at + 1;
// Minimum named character reference is two characters. E.g. `GT`.
if ( $name_at + 2 > $length ) {
return null;
}
$name_length = 0;
$replacement = $html5_named_character_references->read_token( $text, $name_at, $name_length );
if ( false === $replacement ) {
return null;
}
$after_name = $name_at + $name_length;
// If the match ended with a semicolon then it should always be decoded.
if ( ';' === $text[ $name_at + $name_length - 1 ] ) {
$match_byte_length = $after_name - $at;
return $replacement;
}
/*
* At this point though there's a match for an entry in the named
* character reference table but the match doesn't end in `;`.
* It may be allowed if it's followed by something unambiguous.
*/
$ambiguous_follower = (
$after_name < $length &&
$name_at < $length &&
(
ctype_alnum( $text[ $after_name ] ) ||
'=' === $text[ $after_name ]
)
);
// It's non-ambiguous, safe to leave it in.
if ( ! $ambiguous_follower ) {
$match_byte_length = $after_name - $at;
return $replacement;
}
// It's ambiguous, which isn't allowed inside attributes.
if ( 'attribute' === $context ) {
return null;
}
$match_byte_length = $after_name - $at;
return $replacement;
}
