[ Index ]

PHP Cross Reference of WordPress Trunk (Updated Daily)

Search

title

Body

[close]

/wp-includes/html-api/ -> class-wp-html-decoder.php (source)

   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&colon;` or as `&#x68;ttp:` or as `h&#116;tp&colon;`, or in many other ways.
  19       *
  20       * Example:
  21       *
  22       *     $value = 'http&colon;//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( '&#x93;&#x1f604;&#x94' );
  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( '&#x93;&#x1f604;&#x94' );
 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', '&copy;' );
 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&hellip;', 0 );
 185       *     '…'  === WP_HTML_Decoder::read_character_reference( 'attribute', 'Ships&hellip;', 5, $token_length );
 186       *     8    === $token_length; // `&hellip;`
 187       *
 188       *     null === WP_HTML_Decoder::read_character_reference( 'attribute', '&notin', 0 );
 189       *     '∉'  === WP_HTML_Decoder::read_character_reference( 'attribute', '&notin;', 0, $token_length );
 190       *     7    === $token_length; // `&notin;`
 191       *
 192       *     '¬'  === WP_HTML_Decoder::read_character_reference( 'data', '&notin', 0, $token_length );
 193       *     4    === $token_length; // `&not`
 194       *     '∉'  === WP_HTML_Decoder::read_character_reference( 'data', '&notin;', 0, $token_length );
 195       *     7    === $token_length; // `&notin;`
 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 `&#x1f170;` is truncated
 230           * to `&#x1f1` it will encode `DZ`. It does not:
 231           *  - know how to parse the original `🅰`.
 232           *  - fail to parse and return plaintext `&#x1f1`.
 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; // &#x10FFFF;
 247                  ++$digits_at;
 248              } else {
 249                  $numeric_base   = 10;
 250                  $numeric_digits = '0123456789';
 251                  $max_digits     = 7; // &#1114111;
 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  }


Generated : Tue Dec 24 08:20:01 2024 Cross-referenced by PHPXref