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

Сигнатура

wp_kses_hair( string $attr, string[] $allowed_protocols ): array<string,

Описание

Выполняет ряд преобразований при разборе строк атрибутов:
Нормализует значения атрибутов и заключает их в двойные кавычки.
Нормализует ссылки на HTML-символы внутри значений атрибутов.
Удаляет «плохие» URL-протоколы из значений атрибутов.
В остальном читает атрибуты так, как если бы они были частью HTML-тега. Эти преобразования снижают риск ошибочного разбора в дальнейшем и обеспечивают очистку URL в соответствии с остальной подсистемой kses. Важно, что значения атрибутов не декодируются: специальные символы синтаксиса HTML остаются в свойстве value в виде ссылок на символы.
Пример:
$attrs = wp_kses_hair( 'class="is-wide" inert data-lazy=\'<img&#00062\' =/🐮=/' );
$attrs === array(
'class' => array( 'name' => 'class', 'value' => 'is-wide', 'whole' => 'class="is-wide"', 'vless' => 'n' ),
'inert' => array( 'name' => 'inert', 'value' => '', 'whole' => 'inert', 'vless' => 'y' ),
'data-lazy' => array( 'name' => 'data-lazy', 'value' => '<img>', 'whole' => 'data-lazy="<img>"', 'vless' => 'n' ),
'=' => array( 'name' => '=', 'value' => '', 'whole' => '=', 'vless' => 'y' ),
'🐮' => array( 'name' => '🐮', 'value' => '/', 'whole' => '🐮="/"', 'vless' => 'n' ),
);

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

This function performs a number of transformations while parsing attribute strings:

It normalizes attribute values and surrounds them with double quotes.
It normalizes HTML character references inside attribute values.
It removes “bad” URL protocols from attribute values.

Otherwise this reads the attributes as if they were part of an HTML tag. It performs these transformations to lower the risk of mis-parsing down the line and to perform URL sanitization in line with the rest of the kses subsystem. Importantly, it does not decode the attribute values, meaning that special HTML syntax characters will be left with character references in the value property.

Example:

$attrs = wp_kses_hair( 'class="is-wide" inert data-lazy=\'&lt;img&#00062\' =/🐮=/' );
$attrs === array(
    'class'     => array( 'name' => 'class', 'value' => 'is-wide', 'whole' => 'class="is-wide"', 'vless' => 'n' ),
    'inert'     => array( 'name' => 'inert', 'value' => '', 'whole' => 'inert', 'vless' => 'y' ),
    'data-lazy' => array( 'name' => 'data-lazy', 'value' => '&lt;img&gt;', 'whole' => 'data-lazy="&lt;img&gt;"', 'vless' => 'n' ),
    '='         => array( 'name' => '=', 'value' => '', 'whole' => '=', 'vless' => 'y' ),
    '🐮'        => array( 'name' => '🐮', 'value' => '/', 'whole' => '🐮="/"', 'vless' => 'n' ),
);

Параметры

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

Список атрибутов от HTML-элемента до его закрывающего тега.

$allowed_protocols string[] обязательный

Массив разрешённых URL-протоколов.

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

array<string,

'y'|'n'

Исходный код

wp-includes/kses.php:1619

function wp_kses_hair( $attr, $allowed_protocols ) {
	$attributes = array();
	$uris       = wp_kses_uri_attributes();

	$processor = new WP_HTML_Tag_Processor( "<wp {$attr}>" );
	$processor->next_token();

	$attribute_names = $processor->get_attribute_names_with_prefix( '' );
	if ( null === $attribute_names || 0 === count( $attribute_names ) ) {
		return $attributes;
	}

	$syntax_characters = array(
		'&' => '&',
		'<' => '<',
		'>' => '>',
		"'" => '&apos;',
		'"' => '"',
	);

	foreach ( $attribute_names as $name ) {
		$value   = $processor->get_attribute( $name );
		$is_bool = true === $value;
		if ( is_string( $value ) && in_array( $name, $uris, true ) ) {
			$value = wp_kses_bad_protocol( $value, $allowed_protocols );
		}

		// Reconstruct and normalize the attribute value.
		$recoded = $is_bool ? '' : strtr( $value, $syntax_characters );
		$whole   = $is_bool ? $name : "{$name}=\"{$recoded}\"";

		$attributes[ $name ] = array(
			'name'  => $name,
			'value' => $recoded,
			'whole' => $whole,
			'vless' => $is_bool ? 'y' : 'n',
		);
	}

	return $attributes;
}

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

Версия	Описание
7.0.0	Reliably parses HTML via the HTML API.
1.0.0	Introduced.