Exception thrown when the HTML processor encounters unsupported markup.

Source: wp-includes/html-api/class-wp-html-unsupported-exception.php
Since: 6.4.0
Since: 6.7.0 Gained contextual debugging information
Access: private
Extends: Exception

Overview

The HTML API aims to operate in compliance with the HTML5 specification but does not implement the full specification. When it encounters markup it cannot handle safely, it throws this exception rather than producing incorrect output.

This exception is caught internally by the processor and causes parsing to stop gracefully.

Properties

token_name

public $token_name;

Type: string

Normalized name of the matched token when the exception was raised. This doesn’t necessarily mean the token itself was unsupported — it may have triggered an unsupported code path.

token_at

public $token_at;

Type: int

Byte offset into the input HTML where the parser was when the exception was raised.

token

public $token;

Type: string

Full raw text of the matched token. Unlike token_name, this preserves original casing, duplicated attributes, and other syntactic variations.

stack_of_open_elements

public $stack_of_open_elements = array();

Type: string[]

List of element names that were open when the exception was raised. Useful for understanding the parsing context.

active_formatting_elements

public $active_formatting_elements = array();

Type: string[]

List of active formatting element names when the exception was raised.

Methods

__construct()

Creates an unsupported exception with context.

public function __construct(
    string $message,
    string $token_name,
    int $token_at,
    string $token,
    array $stack_of_open_elements,
    array $active_formatting_elements
)

Usage Example

$processor = WP_HTML_Processor::create_fragment( $html );

while ( $processor->next_tag() ) {
    // Process tags...
}

// Check if parsing stopped due to unsupported markup
if ( $processor->get_last_error() ) {
    $exception = $processor->get_unsupported_exception();
    
    if ( $exception ) {
        echo "Unsupported: " . $exception->getMessage() . "n";
        echo "Token: " . $exception->token_name . "n";
        echo "At byte: " . $exception->token_at . "n";
        echo "Raw: " . $exception->token . "n";
        echo "Stack: " . implode( ' > ', $exception->stack_of_open_elements ) . "n";
    }
}

Common Causes

Adoption Agency Algorithm

Complex tag nesting that requires the adoption agency algorithm:

<p><b>Bold <i>Both</b> Italic</i></p>

Foster Parenting

Tables with improperly nested content:

<table><div>This content needs foster parenting</div></table>

Unsupported Elements

Some elements may trigger unsupported code paths in certain contexts.

Debugging Parse Failures

The exception provides all context needed to reproduce and debug failures:

$exception = $processor->get_unsupported_exception();

if ( $exception ) {
    // Show context around the failure
    $html = $processor->get_updated_html();
    $context_start = max( 0, $exception->token_at - 50 );
    $context = substr( $html, $context_start, 100 );
    
    echo "Context: ...{$context}...n";
    echo "Stack: " . implode( ' > ', $exception->stack_of_open_elements ) . "n";
    echo "Formatting: " . implode( ', ', $exception->active_formatting_elements ) . "n";
}