Decodes HTML character references in text content and attributes.

Source: wp-includes/html-api/class-wp-html-decoder.php
Since: 6.6.0

Methods

attribute_starts_with()

Checks if a raw attribute value starts with a given string after decoding.

public static function attribute_starts_with( $haystack, $search_text, $case_sensitivity = 'case-sensitive' ): bool

Returns: true if attribute starts with the search text.

This compares the decoded value, handling all HTML character reference encodings.

Example:

$value = 'http://wordpress.org/';

WP_HTML_Decoder::attribute_starts_with( $value, 'http:', 'ascii-case-insensitive' );
// Returns: true

WP_HTML_Decoder::attribute_starts_with( $value, 'https:', 'ascii-case-insensitive' );
// Returns: false

// Works with any encoding
$encoded = 'http:';
WP_HTML_Decoder::attribute_starts_with( $encoded, 'http:' );
// Returns: true

decode_text_node()

Decodes a text node’s content.

public static function decode_text_node( $text ): string

Returns: Decoded UTF-8 string.

Use this for text between tags (DATA sections), not for attribute values.

Example:

$raw = '“😄”';
$decoded = WP_HTML_Decoder::decode_text_node( $raw );
// Returns: "😄"

decode_attribute()

Decodes an attribute value.

public static function decode_attribute( $text ): string

Returns: Decoded UTF-8 string.

Attribute values have different decoding rules than text nodes. Use this for attribute values.

Example:

$raw = 'Eggs & Milk';
$decoded = WP_HTML_Decoder::decode_attribute( $raw );
// Returns: "Eggs & Milk"

decode()

Low-level decoder for arbitrary HTML text.

public static function decode( $context, $text ): string

Returns: Decoded UTF-8 string.

Example:

WP_HTML_Decoder::decode( 'data', '©' );
// Returns: "©"

read_character_reference()

Reads a character reference at a specific position.

public static function read_character_reference( $context, $text, $at = 0, &$match_byte_length = null )

Returns: Decoded character or null if no reference found.

Example:

$text = 'Ships…';

// No reference at position 0
$result = WP_HTML_Decoder::read_character_reference( 'attribute', $text, 0 );
// Returns: null

// Reference at position 5
$result = WP_HTML_Decoder::read_character_reference( 'attribute', $text, 5, $length );
// Returns: "…"
// $length: 8 (length of "…")

code_point_to_utf8_bytes()

Converts a Unicode code point to UTF-8 bytes.

public static function code_point_to_utf8_bytes( $code_point ): string

Returns: UTF-8 encoded character or "�" for invalid code points.

Example:

WP_HTML_Decoder::code_point_to_utf8_bytes( 0x1f170 );
// Returns: "🅰"

// Invalid code point (half of surrogate pair)
WP_HTML_Decoder::code_point_to_utf8_bytes( 0xd83c );
// Returns: "�"

Character Reference Types

Named References

&     → &
&lt;      → <
&gt;      → >
&quot;    → "
&copy;    → ©
&hellip;  → …

Numeric References (Decimal)

&     → &
&#60;     → <
&#169;    → ©
&#128512; → 😀

Numeric References (Hexadecimal)

&    → &
&#x3C;    → <
&#xA9;    → ©
&#x1F600; → 😀

Context Differences

Attribute Context

In attributes, ambiguous references (not ending in ;) that are followed by alphanumeric characters or = are NOT decoded:

// "&not" followed by "in" is ambiguous in attributes
WP_HTML_Decoder::decode( 'attribute', '&notin' );
// Returns: "&notin" (unchanged)

WP_HTML_Decoder::decode( 'attribute', '∉' );
// Returns: "∉" (decoded)

Data Context

In text content, ambiguous references are decoded:

// "&not" is decoded even without "in"
WP_HTML_Decoder::decode( 'data', '&notin' );
// Returns: "¬in" (¬ = "not")

WP_HTML_Decoder::decode( 'data', '∉' );
// Returns: "∉" (decoded as single character)

C1 Control Character Mapping

Numeric references in the C1 control range (0x80-0x9F) are remapped as if encoded in Windows-1252:

WP_HTML_Decoder::decode( 'data', '€' );
// Returns: "€" (Euro sign, not control character)

WP_HTML_Decoder::decode( 'data', '“' );
// Returns: """ (left double quote)

This matches browser behavior for legacy compatibility.