Document attribute_starts_with()

Author: dmsnell

src/wp-includes/html-api/class-wp-html-decoder.php

@@ -10,38 +10,82 @@
  * @since 6.6.0
  */
 class WP_HTML_Decoder {
-	public static function attribute_starts_with( $attribute_value, $search_text, $case_sensitivity ) {
-		$length     = strlen( $search_text );
-		$loose_case = 'case-insensitive' === $case_sensitivity;
-		$at         = 0;
-		$i          = 0;
-
-		while ( $i < $length && $at < strlen( $attribute_value ) ) {
+	/**
+	 * Indicates if an attribute value starts with a given raw string value.
+	 *
+	 * Use this method to determine if an attribute value starts with a given string, regardless
+	 * of how it might be encoded in HTML. For instance, `http:` could be represented as `http:`
+	 * or as `http&colon;` or as `&#x68;ttp:` or as `h&#116;tp&colon;`, or in many other ways.
+	 *
+	 * Example:
+	 *
+	 *     $value = 'http&colon;//wordpress.org/';
+	 *     true   === WP_HTML_Decoder::attribute_starts_with( $value, 0, null, 'http:', 'case-insensitive' );
+	 *     false  === WP_HTML_Decoder::attribute_starts_with( $value, 0, null, 'https:', 'case-insensitive' );
+	 *
+	 * The `$value_at` and `$value_length` parameters may be used to avoid string allocations when the
+	 * attribute value is found within a larger string.
+	 *
+	 * Example:
+	 *
+	 *     $html = '<a href="h&#116;tps://wordpress.org" title="&copy 2024">';
+	 *     //                 1    1    2    2    3    3    4    4    5    5
+	 *     //       01234567890    5    0    5    0    5    0    5    0    5
+	 *
+	 *     $href  = array( 9, 26 ); // At, Length
+	 *     $title = array( 44, 9 ); // At, Length
+	 *
+	 *     true === WP_HTML_Decode::attribute_starts_with( $html, $href[0], $href[1], 'https://', 'case-insensitive' );
+	 *     true === WP_HTML_Decode::attribute_starts_with( $html, $title[0], $title[1], '©' );
+	 *
+	 *     false === WP_HTML_Decode::attribute_starts_with( $html, $href[0], $href[1], 'http://', 'case-insensitive' );
+	 *     false === WP_HTML_Decode::attribute_starts_with( $html, $title[0], $title[1], '&copy' );
+	 *
+	 * @param string  $raw_haystack     String containing the raw non-decoded attribute value.
+	 * @param int     $value_at         How many bytes into the haystack where the attribute value begins.
+	 * @param int     $value_length     How many bytes the attribute value spans.
+	 *                                  Passing `null` indicates that the value spans to the end of the string.
+	 * @param string  $search_text      Does the attribute value start with this plain string.
+	 * @param ?string $case_sensitivity Set to `case-insensitive` to ignore ASCII case when matching.
+	 *
+	 * @return bool Whether the attribute value starts with the given string.
+	 */
+	public static function attribute_starts_with( $raw_haystack, $value_at, $value_length, $search_text, $case_sensitivity = 'case-sensitive' ) {
+		$search_length = strlen( $search_text );
+		$loose_case    = 'case-insensitive' === $case_sensitivity;
+		$haystack_end  = isset( $value_length ) ? ( $value_at + $value_length ) : strlen( $raw_haystack );
+		$search_at     = 0;
+
+		while ( $search_at < $search_length && $value_at < $haystack_end ) {
 			$chars_match = $loose_case
-				? strtolower( $attribute_value[ $at ] ) === strtolower( $search_text[ $i ] )
-				: $attribute_value[ $at ] === $search_text[ $i ];
+				? strtolower( $raw_haystack[ $value_at ] ) === strtolower( $search_text[ $search_at ] )
+				: $raw_haystack[ $value_at ] === $search_text[ $search_at ];
 
-			$is_introducer = '&' === $attribute_value[ $at ];
+			$is_introducer = '&' === $raw_haystack[ $value_at ];
 			$next_chunk    = $is_introducer
-				? self::read_character_reference( $attribute_value, $at, false, $skip_bytes )
+				? self::read_character_reference( $raw_haystack, $value_at, false, $skip_bytes )
 				: false;
 
+			// If there's no character reference and the characters don't match, the match fails.
 			if ( false === $next_chunk && ! $chars_match ) {
 				return false;
 			}
 
+			// If there's no character reference but the character do match, then it could still match.
 			if ( false === $next_chunk && $chars_match ) {
-				++$at;
-				++$i;
+				++$value_at;
+				++$search_at;
 				continue;
 			}
 
-			if ( 0 !== substr_compare( $search_text, $next_chunk, $i, strlen( $next_chunk ), $loose_case ) ) {
+			// If there is a character reference, then the decoded value must exactly match what follows in the search string.
+			if ( 0 !== substr_compare( $search_text, $next_chunk, $search_at, strlen( $next_chunk ), $loose_case ) ) {
 				return false;
 			}
 
-			$at += $skip_bytes;
-			$i  += strlen( $next_chunk );
+			// The character reference matched, so continue checking.
+			$value_at  += $skip_bytes;
+			$search_at += strlen( $next_chunk );
 		}
 
 		return true;
@@ -263,10 +307,9 @@ public static function read_character_reference( $text, $at, $allow_ambiguous_am
 
 		$after_name = $name_at + $name_length;
 
-		// If we have an un-ambiguous ampersand we can safely leave it in.
+		// If the match ended with a semicolon then it should always be decoded.
 		if ( ';' === $text[ $name_at + $name_length - 1 ] ) {
 			$skip_bytes = $after_name - $at;
-			// @todo bring back the WP_Token_Map so we can decode these.
 			return $name;
 		}
 
@@ -287,7 +330,6 @@ public static function read_character_reference( $text, $at, $allow_ambiguous_am
 		// It's non-ambiguous, safe to leave it in.
 		if ( ! $ambiguous_follower ) {
 			$skip_bytes = $after_name - $at;
-			// @todo Bring back WP_Token_Map to replace properly.
 			return $name;
 		}