WP_HTML_Processor::create_fragment() │ public static │ WP 6.4.0

Creates an HTML processor in the fragment parsing mode.

Use this for cases where you are processing chunks of HTML that will be found within a bigger HTML document, such as rendered block output that exists within a post, the_content a rendered site layout.

Fragment parsing occurs within a context, which is an HTML element that the document will eventually be placed in. It becomes important when special elements have different rules than others, such as inside a TEXTAREA or a TITLE tag where things that look like tags are text, or inside a SCRIPT tag where things that look like HTML syntax are JS.

The context value should be a representation of the tag into which the HTML is found. For most cases this will be the body element. The HTML form is provided because a context element may have attributes that impact the parse, such as with a SCRIPT tag and its type attribute.

Current HTML Support

The only supported context is <body>, which is the default value.
The only supported document encoding is UTF-8, which is the default value.

Method of the class: WP_HTML_Processor{}

No Hooks.

Return

static|null. The created processor if successful, otherwise null.

Usage

$result = WP_HTML_Processor::create_fragment( $html, $context, $encoding );

$html(string) (required): Input HTML fragment to process.
$context(string): Context element for the fragment, must be default of <body>.
Default: '<body>'
$encoding(string): Text encoding of the document; must be default of 'UTF-8'.
Default: 'UTF-8'

Changelog

Since 6.4.0	Introduced.
Since 6.6.0	Returns `static` instead of `self` so it can create subclass instances.

`WP_HTML_Processor::create_fragment() WP HTML Processor::create fragment` code ^{WP 6.6.2}

wp-includes/html-api/class-wp-html-processor.php

public static function create_fragment( $html, $context = '<body>', $encoding = 'UTF-8' ) {
	if ( '<body>' !== $context || 'UTF-8' !== $encoding ) {
		return null;
	}

	$processor                        = new static( $html, self::CONSTRUCTOR_UNLOCK_CODE );
	$processor->state->context_node   = array( 'BODY', array() );
	$processor->state->insertion_mode = WP_HTML_Processor_State::INSERTION_MODE_IN_BODY;

	// @todo Create "fake" bookmarks for non-existent but implied nodes.
	$processor->bookmarks['root-node']    = new WP_HTML_Span( 0, 0 );
	$processor->bookmarks['context-node'] = new WP_HTML_Span( 0, 0 );

	$processor->state->stack_of_open_elements->push(
		new WP_HTML_Token(
			'root-node',
			'HTML',
			false
		)
	);

	$context_node = new WP_HTML_Token(
		'context-node',
		$processor->state->context_node[0],
		false
	);

	$processor->state->stack_of_open_elements->push( $context_node );
	$processor->context_node = $context_node;

	return $processor;
}