WP_HTML_Processor::create_fragment() – Method

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

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

Source

 *
 * @since 6.4.0
 * @since 6.6.0 Returns `static` instead of `self` so it can create subclass instances.
 *
 * @param string $html     Input HTML fragment to process.
 * @param string $context  Context element for the fragment, must be default of `<body>`.
 * @param string $encoding Text encoding of the document; must be default of 'UTF-8'.
 * @return static|null The created processor if successful, otherwise null.
 */
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;
	$processor->state->encoding            = $encoding;
	$processor->state->encoding_confidence = 'certain';

	// @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 );

	$root_node = new WP_HTML_Token(
		'root-node',
		'HTML',
		false
	);

	$processor->state->stack_of_open_elements->push( $root_node );

View all references View on Trac View on GitHub

Changelog

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

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

In this article