WP_HTML_Processor::serialize(): string|null

Returns normalized HTML for a fragment by serializing it.

Description

This differs from WP_HTML_Processor::normalize in that it starts with a specific HTML Processor, which must not have already started scanning; it must be in the initial ready state and will be in the completed state once serialization is complete.

Many aspects of an input HTML fragment may be changed during normalization.

Attribute values will be double-quoted.
Duplicate attributes will be removed.
Omitted tags will be added.
Tag and attribute name casing will be lower-cased, except for specific SVG and MathML tags or attributes.
Text will be re-encoded, null bytes handled, and invalid UTF-8 replaced with U+FFFD.
Any incomplete syntax trailing at the end will be omitted, for example, an unclosed comment opener will be removed.

Example:

$processor = WP_HTML_Processor::create_fragment( '<a href=#anchor v=5 href="/" enabled>One</a another v=5><!--' );
echo $processor->serialize();
// <a href="#anchor" v="5" enabled>One</a>

$processor = WP_HTML_Processor::create_fragment( '<div></p>fun<table><td>cell</div>' );
echo $processor->serialize();
// <div><p></p>fun<table><tbody><tr><td>cell</td></tr></tbody></table></div>

$processor = WP_HTML_Processor::create_fragment( '<![CDATA[invalid comment]]> syntax < <> "oddities"' );
echo $processor->serialize();
// <!--[CDATA[invalid comment]]--> syntax &lt; &lt;&gt; &quot;oddities&quot;

Return

string|null Normalized HTML markup represented by processor, or null if unable to generate serialization.

Source

public function serialize(): ?string {
	if ( WP_HTML_Tag_Processor::STATE_READY !== $this->parser_state ) {
		wp_trigger_error(
			__METHOD__,
			'An HTML Processor which has already started processing cannot serialize its contents. Serialize immediately after creating the instance.',
			E_USER_WARNING
		);
		return null;
	}

	$html = '';
	while ( $this->next_token() ) {
		$html .= $this->serialize_token();
	}

	if ( null !== $this->get_last_error() ) {
		wp_trigger_error(
			__METHOD__,
			"Cannot serialize HTML Processor with parsing error: {$this->get_last_error()}.",
			E_USER_WARNING
		);
		return null;
	}

	return $html;
}

View all references View on Trac View on GitHub

Uses	Description
WP_HTML_Processor::serialize_token()`wp-includes/html-api/class-wp-html-processor.php`	Serializes the currently-matched token.
WP_HTML_Processor::next_token()`wp-includes/html-api/class-wp-html-processor.php`	Finds the next token in the HTML document.
wp_trigger_error()`wp-includes/functions.php`	Generates a user-level error/warning/notice/deprecation message.
WP_HTML_Processor::get_last_error()`wp-includes/html-api/class-wp-html-processor.php`	Returns the last error, if any.

Changelog

Version	Description
6.7.0	Introduced.

User Contributed Notes

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