WP_HTML_Processor::create_fragment( string $html, string $context = ‘<body>’, string $encoding = ‘UTF-8’ ): WP_HTML_Processor|null

Creates an HTML processor in the fragment parsing mode.

Description

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 inside 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.

Parameters

$htmlstringrequired
Input HTML fragment to process.
$contextstringoptional
Context element for the fragment, must be default of <body>.

Default:'<body>'

$encodingstringoptional
Text encoding of the document; must be default of 'UTF-8'.

Default:'UTF-8'

Return

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

Source

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

	$processor                        = new self( $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
		)
	);

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

	return $processor;
}

Changelog

VersionDescription
6.4.0Introduced.

User Contributed Notes

You must log in before being able to contribute a note or feedback.