<!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>[58714] trunk/src/wp-includes/html-api: HTML API: Add context to Unsupported_Exception class for improved debugging.</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/58714">58714</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/58714","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-12 22:27:20 +0000 (Fri, 12 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: Add context to Unsupported_Exception class for improved debugging.

The HTML Processor internally throws an exception when it reaches HTML

that it knows it cannot process, but this exception is not made

available to calling code. It can be useful to extract more knowledge

about why it gave up, especially for debugging purposes.

In this patch, more context is added to the WP_HTML_Unsupported_Exception

and the last exception is made available to calling code through a new

method, `get_unsupported_exception()`.

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

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

Props bernhard-reiter, dmsnell, jonsurrell.

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

<h3>Modified Paths</h3>

<ul>

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

<li><a href="#trunksrcwpincludeshtmlapiclasswphtmlunsupportedexceptionphp">trunk/src/wp-includes/html-api/class-wp-html-unsupported-exception.php</a></li>

</ul>

</div>

<div id="patch">

<h3>Diff</h3>

<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-12 22:18:16 UTC (rev 58713)

+++ trunk/src/wp-includes/html-api/class-wp-html-processor.php  2024-07-12 22:27:20 UTC (rev 58714)

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

</span><span class="cx" style="display: block; padding: 0 10px">        private $last_error = 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">+         * Stores context for why the parser bailed on unsupported HTML, if it did.

+        *

+        * @see self::get_unsupported_exception

+        *

+        * @since 6.7.0

+        *

+        * @var WP_HTML_Unsupported_Exception|null

+        */

+       private $unsupported_exception = null;

+

+       /**

</ins><span class="cx" style="display: block; padding: 0 10px">          * Releases a bookmark when PHP garbage-collects its wrapping WP_HTML_Token instance.

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

</span><span class="cx" style="display: block; padding: 0 10px">         * This function is created inside the class constructor so that it can be passed to

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

</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">+         * Stops the parser and terminates its execution when encountering unsupported markup.

+        *

+        * @throws WP_HTML_Unsupported_Exception Halts execution of the parser.

+        *

+        * @since 6.7.0

+        *

+        * @param string $message Explains support is missing in order to parse the current node.

+        *

+        * @return mixed

+        */

+       private function bail( string $message ) {

+               $here  = $this->bookmarks[ $this->state->current_token->bookmark_name ];

+               $token = substr( $this->html, $here->start, $here->length );

+

+               $open_elements = array();

+               foreach ( $this->state->stack_of_open_elements->stack as $item ) {

+                       $open_elements[] = $item->node_name;

+               }

+

+               $active_formats = array();

+               foreach ( $this->state->active_formatting_elements->walk_down() as $item ) {

+                       $active_formats[] = $item->node_name;

+               }

+

+               $this->last_error = self::ERROR_UNSUPPORTED;

+

+               $this->unsupported_exception = new WP_HTML_Unsupported_Exception(

+                       $message,

+                       $this->state->current_token->node_name,

+                       $here->start,

+                       $token,

+                       $open_elements,

+                       $active_formats

+               );

+

+               throw $this->unsupported_exception;

+       }

+

+       /**

</ins><span class="cx" style="display: block; padding: 0 10px">          * Returns the last error, if any.

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

</span><span class="cx" style="display: block; padding: 0 10px">         * Various situations lead to parsing failure but this class will

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

</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">+         * Returns context for why the parser aborted due to unsupported HTML, if it did.

+        *

+        * This is meant for debugging purposes, not for production use.

+        *

+        * @since 6.7.0

+        *

+        * @see self::$unsupported_exception

+        *

+        * @return WP_HTML_Unsupported_Exception|null

+        */

+       public function get_unsupported_exception() {

+               return $this->unsupported_exception;

+       }

+

+       /**

</ins><span class="cx" style="display: block; padding: 0 10px">          * Finds the next tag matching the $query.

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

<span class="cx" style="display: block; padding: 0 10px">         * @todo Support matching the class name and tag name.

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

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

<span class="cx" style="display: block; padding: 0 10px">                                // This should be unreachable but PHP doesn't have total type checking on switch.

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

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

-                                       throw new WP_HTML_Unsupported_Exception( "Found unrecognized insertion mode '{$this->state->insertion_mode}'." );

</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+                                 $this->bail( "Unaware of the requested parsing mode: '{$this->state->insertion_mode}'." );

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

</span><span class="cx" style="display: block; padding: 0 10px">                } catch ( WP_HTML_Unsupported_Exception $e ) {

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

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