Given a string of HTML attributes and values, parse into a structured attribute list.
Description
This function performs a number of transformations while parsing attribute strings: <ul> <li>It normalizes attribute values and surrounds them with double quotes.</li> <li>It normalizes HTML character references inside attribute values.</li> <li>It removes “bad” URL protocols from attribute values.</li> </ul> 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' ),
);
Parameters
$attrstring
Attribute list from HTML element to closing HTML element tag.
$allowed_protocolsstring[]
Array of allowed URL protocols.
Return
array<string,
array{name: string, value: string, whole: string, vless: 'y'|'n'}> Array of attribute information after parsing.
1623functionwp_kses_hair($attr,$allowed_protocols){1624$attributes=array();1625$uris=wp_kses_uri_attributes();16261627$processor=newWP_HTML_Tag_Processor("<wp {$attr}>");1628$processor->next_token();16291630$attribute_names=$processor->get_attribute_names_with_prefix('');1631if(null===$attribute_names||0===count($attribute_names)){1632return$attributes;1633}16341635$syntax_characters=array(1636'&'=>'&',1637'<'=>'<',1638'>'=>'>',1639"'"=>''',1640'"'=>'"',1641);16421643foreach($attribute_namesas$name){1644$value=$processor->get_attribute($name);1645$is_bool=true===$value;1646if(is_string($value)&&in_array($name,$uris,true)){1647$value=wp_kses_bad_protocol($value,$allowed_protocols);1648}16491650// Reconstruct and normalize the attribute value.1651$recoded=$is_bool?'':strtr($value,$syntax_characters);1652$whole=$is_bool?$name:"{$name}=\"{$recoded}\"";16531654$attributes[$name]=array(1655'name'=>$name,1656'value'=>$recoded,1657'whole'=>$whole,1658'vless'=>$is_bool?'y':'n',1659);1660}16611662return$attributes;1663}
History
Introduced in 1.0.0. One change between 6.7.7 and 7.1.0.
Signature, return type and hooks compared across 5 parsed releases.
7.0.4
Return type changed from array[] to array<string,.verified against source
7.0.0
Reliably parses HTML via the HTML API.from the docblock
1.0.0
Introduced.from the docblock
About this page
Parsed data
Generated from the wordpress-develop 7.0.4 tag, from src/wp-includes/kses.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.
Corrections
Something wrong on this page? Report it and it gets fixed in the next regeneration.