<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"

"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">

<head><meta http-equiv="content-type" content="text/html; charset=utf-8" />

<title>[58836] trunk: HTML API: Introduce full parsing mode in HTML Processor.</title>

</head>

<body>

<style type="text/css"><!--

#msg dl.meta { border: 1px #006 solid; background: #369; padding: 6px; color: #fff; }

#msg dl.meta dt { float: left; width: 6em; font-weight: bold; }

#msg dt:after { content:':';}

#msg dl, #msg dt, #msg ul, #msg li, #header, #footer, #logmsg { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt;  }

#msg dl a { font-weight: bold}

#msg dl a:link    { color:#fc3; }

#msg dl a:active  { color:#ff0; }

#msg dl a:visited { color:#cc6; }

h3 { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; font-weight: bold; }

#msg pre { white-space: pre-line; overflow: auto; background: #ffc; border: 1px #fa0 solid; padding: 6px; }

#logmsg { background: #ffc; border: 1px #fa0 solid; padding: 1em 1em 0 1em; }

#logmsg p, #logmsg pre, #logmsg blockquote { margin: 0 0 1em 0; }

#logmsg p, #logmsg li, #logmsg dt, #logmsg dd { line-height: 14pt; }

#logmsg h1, #logmsg h2, #logmsg h3, #logmsg h4, #logmsg h5, #logmsg h6 { margin: .5em 0; }

#logmsg h1:first-child, #logmsg h2:first-child, #logmsg h3:first-child, #logmsg h4:first-child, #logmsg h5:first-child, #logmsg h6:first-child { margin-top: 0; }

#logmsg ul, #logmsg ol { padding: 0; list-style-position: inside; margin: 0 0 0 1em; }

#logmsg ul { text-indent: -1em; padding-left: 1em; }#logmsg ol { text-indent: -1.5em; padding-left: 1.5em; }

#logmsg > ul, #logmsg > ol { margin: 0 0 1em 0; }

#logmsg pre { background: #eee; padding: 1em; }

#logmsg blockquote { border: 1px solid #fa0; border-left-width: 10px; padding: 1em 1em 0 1em; background: white;}

#logmsg dl { margin: 0; }

#logmsg dt { font-weight: bold; }

#logmsg dd { margin: 0; padding: 0 0 0.5em 0; }

#logmsg dd:before { content:'\00bb';}

#logmsg table { border-spacing: 0px; border-collapse: collapse; border-top: 4px solid #fa0; border-bottom: 1px solid #fa0; background: #fff; }

#logmsg table th { text-align: left; font-weight: normal; padding: 0.2em 0.5em; border-top: 1px dotted #fa0; }

#logmsg table td { text-align: right; border-top: 1px dotted #fa0; padding: 0.2em 0.5em; }

#logmsg table thead th { text-align: center; border-bottom: 1px solid #fa0; }

#logmsg table th.Corner { text-align: left; }

#logmsg hr { border: none 0; border-top: 2px dashed #fa0; height: 1px; }

#header, #footer { color: #fff; background: #636; border: 1px #300 solid; padding: 6px; }

#patch { width: 100%; }

#patch h4 {font-family: verdana,arial,helvetica,sans-serif;font-size:10pt;padding:8px;background:#369;color:#fff;margin:0;}

#patch .propset h4, #patch .binary h4 {margin:0;}

#patch pre {padding:0;line-height:1.2em;margin:0;}

#patch .diff {width:100%;background:#eee;padding: 0 0 10px 0;overflow:auto;}

#patch .propset .diff, #patch .binary .diff  {padding:10px 0;}

#patch span {display:block;padding:0 10px;}

#patch .modfile, #patch .addfile, #patch .delfile, #patch .propset, #patch .binary, #patch .copfile {border:1px solid #ccc;margin:10px 0;}

#patch ins {background:#dfd;text-decoration:none;display:block;padding:0 10px;}

#patch del {background:#fdd;text-decoration:none;display:block;padding:0 10px;}

#patch .lines, .info {color:#888;background:#fff;}

--></style>

<div id="msg">

<dl class="meta" style="font-size: 105%">

<dt style="float: left; width: 6em; font-weight: bold">Revision</dt> <dd><a style="font-weight: bold" href="https://core.trac.wordpress.org/changeset/58836">58836</a><script type="application/ld+json">{"@context":"http://schema.org","@type":"EmailMessage","description":"Review this Commit","action":{"@type":"ViewAction","url":"https://core.trac.wordpress.org/changeset/58836","name":"Review Commit"}}</script></dd>

<dt style="float: left; width: 6em; font-weight: bold">Author</dt> <dd>dmsnell</dd>

<dt style="float: left; width: 6em; font-weight: bold">Date</dt> <dd>2024-07-31 16:54:23 +0000 (Wed, 31 Jul 2024)</dd>

</dl>

<pre style='padding-left: 1em; margin: 2em 0; border-left: 2px solid #ccc; line-height: 1.25; font-size: 105%; font-family: sans-serif'>HTML API: Introduce full parsing mode in HTML Processor.

The HTML Processor has only supported a specific kind of parsing mode

called _the fragment parsing mode_, where it behaves in the same way

that `node.innerHTML = html` does in the DOM. This mode assumes a

context node and doesn't support parsing an entire document.

As part of work to add more spec support to the HTML API, this patch

introduces a full parsing mode, which can parse a full HTML document

from start to end, including the doctype declaration and head tags.

Developed in https://github.com/wordpress/wordpress-develop/pull/6977

Discussed in https://core.trac.wordpress.org/ticket/61576

Props: dmsnell, jonsurrell.

See <a href="https://core.trac.wordpress.org/ticket/61576">#61576</a>.</pre>

<h3>Modified Paths</h3>

<ul>

<li><a href="#trunksrcwpincludeshtmlapiclasswphtmlprocessorstatephp">trunk/src/wp-includes/html-api/class-wp-html-processor-state.php</a></li>

<li><a href="#trunksrcwpincludeshtmlapiclasswphtmlprocessorphp">trunk/src/wp-includes/html-api/class-wp-html-processor.php</a></li>

<li><a href="#trunktestsphpunittestshtmlapiwpHtmlProcessorBreadcrumbsphp">trunk/tests/phpunit/tests/html-api/wpHtmlProcessorBreadcrumbs.php</a></li>

</ul>

</div>

<div id="patch">

<h3>Diff</h3>

<a id="trunksrcwpincludeshtmlapiclasswphtmlprocessorstatephp"></a>

<div class="modfile"><h4 style="background-color: #eee; color: inherit; margin: 1em 0; padding: 1.3em; font-size: 115%">Modified: trunk/src/wp-includes/html-api/class-wp-html-processor-state.php</h4>

<pre class="diff"><span>

<span class="info" style="display: block; padding: 0 10px; color: #888">--- trunk/src/wp-includes/html-api/class-wp-html-processor-state.php  2024-07-31 14:03:24 UTC (rev 58835)

+++ trunk/src/wp-includes/html-api/class-wp-html-processor-state.php    2024-07-31 16:54:23 UTC (rev 58836)

</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -429,6 +429,38 @@

</span><span class="cx" style="display: block; padding: 0 10px">        public $context_node = null;

</span><span class="cx" style="display: block; padding: 0 10px"> 

</span><span class="cx" style="display: block; padding: 0 10px">        /**

<ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+         * The recognized encoding of the input byte stream.

+        *

+        * > The stream of code points that comprises the input to the tokenization

+        * > stage will be initially seen by the user agent as a stream of bytes

+        * > (typically coming over the network or from the local file system).

+        * > The bytes encode the actual characters according to a particular character

+        * > encoding, which the user agent uses to decode the bytes into characters.

+        *

+        * @since 6.7.0

+        *

+        * @var string|null

+        */

+       public $encoding = null;

+

+       /**

+        * The parser's confidence in the input encoding.

+        *

+        * > When the HTML parser is decoding an input byte stream, it uses a character

+        * > encoding and a confidence. The confidence is either tentative, certain, or

+        * > irrelevant. The encoding used, and whether the confidence in that encoding

+        * > is tentative or certain, is used during the parsing to determine whether to

+        * > change the encoding. If no encoding is necessary, e.g. because the parser is

+        * > operating on a Unicode stream and doesn't have to use a character encoding

+        * > at all, then the confidence is irrelevant.

+        *

+        * @since 6.7.0

+        *

+        * @var string

+        */

+       public $encoding_confidence = 'tentative';

+

+       /**

</ins><span class="cx" style="display: block; padding: 0 10px">          * HEAD element pointer.

</span><span class="cx" style="display: block; padding: 0 10px">         *

</span><span class="cx" style="display: block; padding: 0 10px">         * @since 6.7.0

</span></span></pre></div>

<a id="trunksrcwpincludeshtmlapiclasswphtmlprocessorphp"></a>

<div class="modfile"><h4 style="background-color: #eee; color: inherit; margin: 1em 0; padding: 1.3em; font-size: 115%">Modified: trunk/src/wp-includes/html-api/class-wp-html-processor.php</h4>

<pre class="diff"><span>

<span class="info" style="display: block; padding: 0 10px; color: #888">--- trunk/src/wp-includes/html-api/class-wp-html-processor.php        2024-07-31 14:03:24 UTC (rev 58835)

+++ trunk/src/wp-includes/html-api/class-wp-html-processor.php  2024-07-31 16:54:23 UTC (rev 58836)

</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -256,21 +256,6 @@

</span><span class="cx" style="display: block; padding: 0 10px">         */

</span><span class="cx" style="display: block; padding: 0 10px">        private $context_node = null;

</span><span class="cx" style="display: block; padding: 0 10px"> 

</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">-        /**

-        * Whether the parser has yet processed the context node,

-        * if created as a fragment parser.

-        *

-        * The context node will be initially pushed onto the stack of open elements,

-        * but when created as a fragment parser, this context element (and the implicit

-        * HTML document node above it) should not be exposed as a matched token or node.

-        *

-        * This boolean indicates whether the processor should skip over the current

-        * node in its initial search for the first node created from the input HTML.

-        *

-        * @var bool

-        */

-       private $has_seen_context_node = false;

-

</del><span class="cx" style="display: block; padding: 0 10px">         /*

</span><span class="cx" style="display: block; padding: 0 10px">         * Public Interface Functions

</span><span class="cx" style="display: block; padding: 0 10px">         */

</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -312,9 +297,11 @@

</span><span class="cx" style="display: block; padding: 0 10px">                        return null;

</span><span class="cx" style="display: block; padding: 0 10px">                }

</span><span class="cx" style="display: block; padding: 0 10px"> 

</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">-                $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;

</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+         $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';

</ins><span class="cx" style="display: block; padding: 0 10px"> 

<span class="cx" style="display: block; padding: 0 10px">                // @todo Create "fake" bookmarks for non-existent but implied nodes.

</span><span class="cx" style="display: block; padding: 0 10px">                $processor->bookmarks['root-node']    = new WP_HTML_Span( 0, 0 );

</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -341,6 +328,34 @@

</span><span class="cx" style="display: block; padding: 0 10px">        }

</span><span class="cx" style="display: block; padding: 0 10px"> 

</span><span class="cx" style="display: block; padding: 0 10px">        /**

<ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+         * Creates an HTML processor in the full parsing mode.

+        *

+        * It's likely that a fragment parser is more appropriate, unless sending an

+        * entire HTML document from start to finish. Consider a fragment parser with

+        * a context node of `<body>`.

+        *

+        * Since UTF-8 is the only currently-accepted charset, if working with a

+        * document that isn't UTF-8, it's important to convert the document before

+        * creating the processor: pass in the converted HTML.

+        *

+        * @param string      $html                    Input HTML document to process.

+        * @param string|null $known_definite_encoding Optional. If provided, specifies the charset used

+        *                                             in the input byte stream. Currently must be UTF-8.

+        * @return static|null The created processor if successful, otherwise null.

+        */

+       public static function create_full_parser( $html, $known_definite_encoding = 'UTF-8' ) {

+               if ( 'UTF-8' !== $known_definite_encoding ) {

+                       return null;

+               }

+

+               $processor                             = new static( $html, self::CONSTRUCTOR_UNLOCK_CODE );

+               $processor->state->encoding            = $known_definite_encoding;

+               $processor->state->encoding_confidence = 'certain';

+

+               return $processor;

+       }

+

+       /**

</ins><span class="cx" style="display: block; padding: 0 10px">          * Constructor.

</span><span class="cx" style="display: block; padding: 0 10px">         *

<span class="cx" style="display: block; padding: 0 10px">         * Do not use this method. Use the static creator methods instead.

</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -993,7 +1008,62 @@