Update docs, fix bug, pass invalid UTF-8 un-obscured.

Author: dmsnell

src/wp-includes/formatting.php

@@ -2901,7 +2901,33 @@ function urldecode_deep( $value ) {
 }
 
 /**
- * Converts email addresses characters to HTML entities to block spam bots.
+ * Obscures email addresses in HTML to prevent spam bots from harvesting them.
+ *
+ * Typically this will randomly replace characters from the email address with
+ * HTML character references; however, when the hex encoding parameter is set,
+ * some characters will also be represented in their percent-encoded form.
+ *
+ * Because this function is randomized, the outputs for any given input may
+ * differ between calls. This helps diversify the ways the email addresses
+ * are obscured.
+ *
+ * When non-UTF-8 inputs are provided, any spans of invalid UTF-8 bytes will
+ * be passed through without any obfuscation.
+ *
+ * Example:
+ *
+ *     $email      = 'noreply@example.com';
+ *     $obscured   = antispambot( $email );
+ *     $obscured === 'noreply@example.com';
+ *
+ *     // Hex-encoding also obscures characters with percent-encoding.
+ *     $obscured   = antispambot( $email, 1 );
+ *     $obscured === '%6eore%70l%79@%65x%61mple%2e%63%6fm';
+ *
+ *     // Non-UTF-8 characters are not obfuscated. "\xFC" is Latin1 "ü".
+ *     $obscured   = antispambot( "b\xFCcher@library.de" );
+ *     $obscured === 'b�cher@library.de';
+ *     $obscured === "b\xFCcher@library.de"
  *
  * @since 0.71
  * @since {WP_VERSION} Masquerades multi-byte characters.
@@ -2911,45 +2937,49 @@ function urldecode_deep( $value ) {
  * @return string Converted email address.
  */
 function antispambot( $email_address, $hex_encoding = 0 ) {
-	/*
-	 * Email addresses passed into this function should not contain invalid UTF-8, but if they do,
-	 * enforce the constraint by refusing to print any email address.
-	 */
-	if ( ! wp_check_invalid_utf8( $email_address ) ) {
-		return '';
-	}
-
 	$obfuscated     = '';
 	$at             = 0;
-	$next_at        = 0;
 	$end            = strlen( $email_address );
 	$invalid_length = 0;
+
 	while ( $at < $end ) {
-		if ( 0 === _wp_scan_utf8( $email_address, $next_at, $invalid_length, null, 1 ) ) {
+		$was_at = $at;
+		if (
+			0 === _wp_scan_utf8( $email_address, $at, $invalid_length, null, 1 ) &&
+			0 === $invalid_length
+		) {
 			break;
 		}
 
-		$character = substr( $email_address, $at, $next_at - $at );
+		$character_length = $at - $was_at;
 
-		switch ( rand( 0, 1 + $hex_encoding ) ) {
-			case 0:
-				$code_point             = mb_ord( $character );
-				$obfuscated .= "&#{$code_point};";
-				break;
+		if ( $character_length > 0 ) {
+			$character = substr( $email_address, $was_at, $character_length );
 
-			case 1:
-				$obfuscated .= $character;
-				break;
+			switch ( rand( 0, 1 + $hex_encoding ) ) {
+				case 0:
+					$code_point  = mb_ord( $character );
+					$obfuscated .= "&#{$code_point};";
+					break;
 
-			case 2:
-				for ( $i = 0, $byte_count = strlen( $character ); $i < $byte_count; $i++ ) {
-					$hex_value              = bin2hex( $character[ $i ] );
-					$obfuscated .= "%{$hex_value}";
-				}
-				break;
+				case 1:
+					$obfuscated .= $character;
+					break;
+
+				case 2:
+					for ( $i = 0; $i < $character_length; $i++ ) {
+						$hex_value   = bin2hex( $character[ $i ] );
+						$obfuscated .= "%{$hex_value}";
+					}
+					break;
+			}
+		}
+
+		if ( 0 !== $invalid_length ) {
+			$obfuscated .= substr( $email_address, $at, $invalid_length );
 		}
 
-		$at = $next_at;
+		$at += $invalid_length;
 	}
 
 	return str_replace( '@', '&#64;', $obfuscated );