Changeset 58714

Timestamp:

07/12/2024 10:27:20 PM (4 weeks ago)

Author:

dmsnell

Message:

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 #61646.

Location:

trunk/src/wp-includes/html-api

Files:

• class-wp-html-processor.php (modified) (30 diffs)
• class-wp-html-unsupported-exception.php (modified) (2 diffs)

trunk/src/wp-includes/html-api/class-wp-html-processor.php

@@ -190 +190 @@
 
     /**
+
+
+
+
+
+
+
+
+
+
+
      * Releases a bookmark when PHP garbage-collects its wrapping WP_HTML_Token instance.
      *
@@ -386 +397 @@
 
     /**
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
      * Returns the last error, if any.
      *
@@ -410 +460 @@
     public function get_last_error() {
         return $this->last_error;
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
     }
 
@@ -842 +907 @@
                 // This should be unreachable but PHP doesn't have total type checking on switch.
                 default:
-                    $this->last_error = self::ERROR_UNSUPPORTED;
-                    throw new WP_HTML_Unsupported_Exception( "Found unrecognized insertion mode '{$this->state->insertion_mode}'." );
+                    $this->bail( "Unaware of the requested parsing mode: '{$this->state->insertion_mode}'." );
             }
         } catch ( WP_HTML_Unsupported_Exception $e ) {
@@ -923 +987 @@
      */
     private function step_initial() {
-        $this->last_error = self::ERROR_UNSUPPORTED;
-        throw new WP_HTML_Unsupported_Exception( "No support for parsing in the '{$this->state->insertion_mode}' state." );
+        $this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
     }
 
@@ -943 +1006 @@
      */
     private function step_before_html() {
-        $this->last_error = self::ERROR_UNSUPPORTED;
-        throw new WP_HTML_Unsupported_Exception( "No support for parsing in the '{$this->state->insertion_mode}' state." );
+        $this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
     }
 
@@ -963 +1025 @@
      */
     private function step_before_head() {
-        $this->last_error = self::ERROR_UNSUPPORTED;
-        throw new WP_HTML_Unsupported_Exception( "No support for parsing in the '{$this->state->insertion_mode}' state." );
+        $this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
     }
 
@@ -983 +1044 @@
      */
     private function step_in_head() {
-        $this->last_error = self::ERROR_UNSUPPORTED;
-        throw new WP_HTML_Unsupported_Exception( "No support for parsing in the '{$this->state->insertion_mode}' state." );
+        $this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
     }
 
@@ -1003 +1063 @@
      */
     private function step_in_head_noscript() {
-        $this->last_error = self::ERROR_UNSUPPORTED;
-        throw new WP_HTML_Unsupported_Exception( "No support for parsing in the '{$this->state->insertion_mode}' state." );
+        $this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
     }
 
@@ -1023 +1082 @@
      */
     private function step_after_head() {
-        $this->last_error = self::ERROR_UNSUPPORTED;
-        throw new WP_HTML_Unsupported_Exception( "No support for parsing in the '{$this->state->insertion_mode}' state." );
+        $this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
     }
 
@@ -1446 +1504 @@
              */
             case '-BR':
-                $this->last_error = self::ERROR_UNSUPPORTED;
-                throw new WP_HTML_Unsupported_Exception( 'Closing BR tags require unimplemented special handling.' );
+                $this->bail( 'Closing BR tags require unimplemented special handling.' );
+                // This return required because PHPCS can't determine that the call to bail() throws.
+                return false;
 
             /*
@@ -1603 +1662 @@
             case 'TR':
             case 'XMP':
-                $this->last_error = self::ERROR_UNSUPPORTED;
-                throw new WP_HTML_Unsupported_Exception( "Cannot process {$token_name} element." );
+                $this->bail( "Cannot process {$token_name} element." );
         }
 
@@ -1666 +1724 @@
      */
     private function step_in_table() {
-        $this->last_error = self::ERROR_UNSUPPORTED;
-        throw new WP_HTML_Unsupported_Exception( "No support for parsing in the '{$this->state->insertion_mode}' state." );
+        $this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
     }
 
@@ -1686 +1743 @@
      */
     private function step_in_table_text() {
-        $this->last_error = self::ERROR_UNSUPPORTED;
-        throw new WP_HTML_Unsupported_Exception( "No support for parsing in the '{$this->state->insertion_mode}' state." );
+        $this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
     }
 
@@ -1706 +1762 @@
      */
     private function step_in_caption() {
-        $this->last_error = self::ERROR_UNSUPPORTED;
-        throw new WP_HTML_Unsupported_Exception( "No support for parsing in the '{$this->state->insertion_mode}' state." );
+        $this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
     }
 
@@ -1726 +1781 @@
      */
     private function step_in_column_group() {
-        $this->last_error = self::ERROR_UNSUPPORTED;
-        throw new WP_HTML_Unsupported_Exception( "No support for parsing in the '{$this->state->insertion_mode}' state." );
+        $this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
     }
 
@@ -1746 +1800 @@
      */
     private function step_in_table_body() {
-        $this->last_error = self::ERROR_UNSUPPORTED;
-        throw new WP_HTML_Unsupported_Exception( "No support for parsing in the '{$this->state->insertion_mode}' state." );
+        $this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
     }
 
@@ -1766 +1819 @@
      */
     private function step_in_row() {
-        $this->last_error = self::ERROR_UNSUPPORTED;
-        throw new WP_HTML_Unsupported_Exception( "No support for parsing in the '{$this->state->insertion_mode}' state." );
+        $this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
     }
 
@@ -1786 +1838 @@
      */
     private function step_in_cell() {
-        $this->last_error = self::ERROR_UNSUPPORTED;
-        throw new WP_HTML_Unsupported_Exception( "No support for parsing in the '{$this->state->insertion_mode}' state." );
+        $this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
     }
 
@@ -1987 +2038 @@
      */
     private function step_in_select_in_table() {
-        $this->last_error = self::ERROR_UNSUPPORTED;
-        throw new WP_HTML_Unsupported_Exception( "No support for parsing in the '{$this->state->insertion_mode}' state." );
+        $this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
     }
 
@@ -2007 +2057 @@
      */
     private function step_in_template() {
-        $this->last_error = self::ERROR_UNSUPPORTED;
-        throw new WP_HTML_Unsupported_Exception( "No support for parsing in the '{$this->state->insertion_mode}' state." );
+        $this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
     }
 
@@ -2027 +2076 @@
      */
     private function step_after_body() {
-        $this->last_error = self::ERROR_UNSUPPORTED;
-        throw new WP_HTML_Unsupported_Exception( "No support for parsing in the '{$this->state->insertion_mode}' state." );
+        $this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
     }
 
@@ -2047 +2095 @@
      */
     private function step_in_frameset() {
-        $this->last_error = self::ERROR_UNSUPPORTED;
-        throw new WP_HTML_Unsupported_Exception( "No support for parsing in the '{$this->state->insertion_mode}' state." );
+        $this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
     }
 
@@ -2067 +2114 @@
      */
     private function step_after_frameset() {
-        $this->last_error = self::ERROR_UNSUPPORTED;
-        throw new WP_HTML_Unsupported_Exception( "No support for parsing in the '{$this->state->insertion_mode}' state." );
+        $this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
     }
 
@@ -2087 +2133 @@
      */
     private function step_after_after_body() {
-        $this->last_error = self::ERROR_UNSUPPORTED;
-        throw new WP_HTML_Unsupported_Exception( "No support for parsing in the '{$this->state->insertion_mode}' state." );
+        $this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
     }
 
@@ -2107 +2152 @@
      */
     private function step_after_after_frameset() {
-        $this->last_error = self::ERROR_UNSUPPORTED;
-        throw new WP_HTML_Unsupported_Exception( "No support for parsing in the '{$this->state->insertion_mode}' state." );
+        $this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
     }
 
@@ -2127 +2171 @@
      */
     private function step_in_foreign_content() {
-        $this->last_error = self::ERROR_UNSUPPORTED;
-        throw new WP_HTML_Unsupported_Exception( "No support for parsing in the '{$this->state->insertion_mode}' state." );
+        $this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
     }
 
@@ -2836 +2879 @@
         }
 
-        $this->last_error = self::ERROR_UNSUPPORTED;
-        throw new WP_HTML_Unsupported_Exception( 'Cannot reconstruct active formatting elements when advancing and rewinding is required.' );
+        $this->bail( 'Cannot reconstruct active formatting elements when advancing and rewinding is required.' );
     }
 
@@ -3073 +3115 @@
             // > If there is no such element, then return and instead act as described in the "any other end tag" entry above.
             if ( null === $formatting_element ) {
-                $this->last_error = self::ERROR_UNSUPPORTED;
-                throw new WP_HTML_Unsupported_Exception( 'Cannot run adoption agency when "any other end tag" is required.' );
+                $this->bail( 'Cannot run adoption agency when "any other end tag" is required.' );
             }
 
@@ -3126 +3167 @@
             }
 
-            $this->last_error = self::ERROR_UNSUPPORTED;
-            throw new WP_HTML_Unsupported_Exception( 'Cannot extract common ancestor in adoption agency algorithm.' );
-        }
-
-        $this->last_error = self::ERROR_UNSUPPORTED;
-        throw new WP_HTML_Unsupported_Exception( 'Cannot run adoption agency when looping required.' );
+            $this->bail( 'Cannot extract common ancestor in adoption agency algorithm.' );
+        }
+
+        $this->bail( 'Cannot run adoption agency when looping required.' );
     }
 

trunk/src/wp-includes/html-api/class-wp-html-unsupported-exception.php

@@ -22 +22 @@
  *
  * @since 6.4.0
+
  *
  * @access private
@@ -28 +29 @@
  */
 class WP_HTML_Unsupported_Exception extends Exception {
+
+
+
+
+
+
+
+
+
+
+
+
+
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 }