wp_check_invalid_utf8() — описание функции WordPress на русском

Сигнатура

wp_check_invalid_utf8( string $text, bool $strip = false ): string

Описание

Внимание! Эта функция выполняет свою работу только если blog_charset установлен в UTF-8. Для всех остальных значений она возвращает входной текст без изменений.
Внимание! Если не указано иное, функция возвращает пустую строку, когда входные данные содержат любые последовательности недопустимого UTF-8. Чтобы заменить недопустимые последовательности байтов, передайте true в необязательном параметре $strip.
Стоит рассмотреть использование wp_scrub_utf8(), которое не зависит от значения blog_charset.
Пример:
// `blog_charset` равен `latin1`, поэтому здесь входные данные возвращаются без изменений.
$every_possible_input === wp_check_invalid_utf8( $every_possible_input );

// Корректные строки проходят без изменений.
'test' === wp_check_invalid_utf8( 'test' );

$invalid = "the byte xC0 is never allowed in a UTF-8 string.";

// Недопустимые строки отклоняются полностью.
'' === wp_check_invalid_utf8( $invalid );

// «Удаление» недопустимых последовательностей вместо этого даёт символ замены.
"the byte \u{FFFD} is never allowed in a UTF-8 string." === wp_check_invalid_utf8( $invalid, true );
'the byte � is never allowed in a UTF-8 string.' === wp_check_invalid_utf8( $invalid, true );

Оригинал (английский)

Note! This function only performs its work if the blog_charset is set to UTF-8. For all other values it returns the input text unchanged.

Note! Unless requested, this returns an empty string if the input contains any sequences of invalid UTF-8. To replace invalid byte sequences, pass true as the optional $strip parameter.

Consider using wp_scrub_utf8() instead which does not depend on the value of blog_charset.

Example:

// The `blog_charset` is `latin1`, so this returns the input unchanged.
$every_possible_input === wp_check_invalid_utf8( $every_possible_input );

// Valid strings come through unchanged.
'test' === wp_check_invalid_utf8( 'test' );

$invalid = "the byte xC0 is never allowed in a UTF-8 string.";

// Invalid strings are rejected outright.
'' === wp_check_invalid_utf8( $invalid );

// “Stripping” invalid sequences produces the replacement character instead.
"the byte \u{FFFD} is never allowed in a UTF-8 string." === wp_check_invalid_utf8( $invalid, true );
'the byte � is never allowed in a UTF-8 string.' === wp_check_invalid_utf8( $invalid, true );

Параметры

$text string обязательный

Строка, которая, как предполагается, закодирована в UTF-8, если только blog_charset не задаёт другую кодировку.

$strip bool необязательный = false

Заменять ли недопустимые последовательности байтов символом замены Unicode (U+FFFD �). При значении по умолчанию false для недопустимых UTF-8 данных возвращается пустая строка.

Возвращаемое значение

string

Исходный код

wp-includes/formatting.php:1127

function wp_check_invalid_utf8( $text, $strip = false ) {
	$text = (string) $text;

	if ( 0 === strlen( $text ) ) {
		return '';
	}

	// Store the site charset as a static to avoid multiple calls to get_option().
	static $is_utf8 = null;
	if ( ! isset( $is_utf8 ) ) {
		$is_utf8 = is_utf8_charset();
	}

	if ( ! $is_utf8 || wp_is_valid_utf8( $text ) ) {
		return $text;
	}

	return $strip
		? wp_scrub_utf8( $text )
		: '';
}

История изменений

Версия	Описание
6.9.0	Stripping replaces invalid byte sequences with the Unicode replacement character U+FFFD (�).
2.8.0	Introduced.