Changeset 58304

Timestamp:

06/03/2024 07:45:57 PM (8 weeks ago)

Author:

dmsnell

Message:

HTML API: Report real and virtual nodes in the HTML Processor.

HTML is a kind of short-hand for a DOM structure. This means that there are
many cases in HTML where an element's opening tag or closing tag is missing (or
both). This is because many of the parsing rules imply creating elements in the
DOM which may not exist in the text of the HTML.

The HTML Processor, being the higher-level counterpart to the Tag Processor, is
already aware of these nodes, but since it's inception has not paused on them
when scanning through a document. Instead, these are visible when pausing on a
child of such an element, but otherwise not seen.

In this patch the HTML Processor starts exposing those implicitly-created nodes,
including opening tags, and closing tags, that aren't foudn in the text content
of the HTML input document.

Previously, the sequence of matched tokens when scanning with
WP_HTML_Processor::next_token() would depend on how the HTML document was written,
but with this patch, all semantically equal HTML documents will parse and scan in
the same exact manner, presenting an idealized or "perfect" view of the document
the same way as would occur when traversing a DOM in a browser.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/6348
Discussed in https://core.trac.wordpress.org/ticket/61348

Props audrasjb, dmsnell, gziolo, jonsurrell.
Fixes #61348.

Location:

trunk

Files:

• src/wp-includes/html-api/class-wp-html-open-elements.php (modified) (3 diffs)
• src/wp-includes/html-api/class-wp-html-processor.php (modified) (20 diffs)
• src/wp-includes/html-api/class-wp-html-stack-event.php (added)
• src/wp-settings.php (modified) (1 diff)
• tests/phpunit/tests/html-api/wpHtmlProcessorBreadcrumbs.php (modified) (3 diffs)
• tests/phpunit/tests/html-api/wpHtmlProcessorSemanticRules.php (modified) (1 diff)

trunk/src/wp-includes/html-api/class-wp-html-open-elements.php

@@ -53 +53 @@
 
     /**
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
      * Reports if a specific node is in the stack of open elements.
      *
@@ -430 +480 @@
                 break;
         }
+
+
+
+
     }
 
@@ -459 +513 @@
                 break;
         }
+
+
+
+
     }
 }

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

@@ -202 +202 @@
     private $release_internal_bookmark_on_destruct = null;
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
     /*
      * Public Interface Functions
@@ -258 +304 @@
         );
 
-        $processor->state->stack_of_open_elements->push(
-            new WP_HTML_Token(
-                'context-node',
-                $processor->state->context_node[0],
-                false
-            )
+        $context_node = new WP_HTML_Token(
+            'context-node',
+            $processor->state->context_node[0],
+            false
         );
+
+
+
 
         return $processor;
@@ -300 +347 @@
         $this->state = new WP_HTML_Processor_State();
 
+
+
+
+
+
+
+
+
+
+
+
+
         /*
          * Create this wrapper so that it's possible to pass
@@ -343 +402 @@
      *
      * @since 6.4.0
+
      *
      * @throws Exception When unable to allocate a bookmark for the next token in the input HTML document.
@@ -350 +410 @@
      *
      *     @type string|null $tag_name     Which tag to find, or `null` for "any tag."
+
      *     @type int|null    $match_offset Find the Nth tag matching all search criteria.
      *                                     1 for "first" tag, 3 for "third," etc.
@@ -360 +421 @@
      */
     public function next_tag( $query = null ) {
+
+
         if ( null === $query ) {
-            while ( $this->step() ) {
+            while ( $this->() ) {
                 if ( '#tag' !== $this->get_token_type() ) {
                     continue;
                 }
 
-                if ( ! $this->is_tag_closer() ) {
+                if ( ! $this ) {
                     return true;
                 }
@@ -392 +455 @@
 
         if ( ! ( array_key_exists( 'breadcrumbs', $query ) && is_array( $query['breadcrumbs'] ) ) ) {
-            while ( $this->step() ) {
+            while ( $this->() ) {
                 if ( '#tag' !== $this->get_token_type() ) {
                     continue;
@@ -401 +464 @@
                 }
 
-                if ( ! $this->is_tag_closer() ) {
+                if ( !  ) {
                     return true;
                 }
             }
 
-            return false;
-        }
-
-        if ( isset( $query['tag_closers'] ) && 'visit' === $query['tag_closers'] ) {
-            _doing_it_wrong(
-                __METHOD__,
-                __( 'Cannot visit tag closers in HTML Processor.' ),
-                '6.4.0'
-            );
             return false;
         }
@@ -421 +475 @@
         $match_offset = isset( $query['match_offset'] ) ? (int) $query['match_offset'] : 1;
 
-        while ( $match_offset > 0 && $this->step() ) {
-            if ( '#tag' !== $this->get_token_type() ) {
+        while ( $match_offset > 0 && $this->() ) {
+            if ( '#tag' !== $this->get_token_type() ) {
                 continue;
             }
@@ -453 +507 @@
      */
     public function next_token() {
-        return $this->step();
+        $this->current_element = null;
+
+        if ( isset( $this->last_error ) ) {
+            return false;
+        }
+
+        if ( 0 === count( $this->element_queue ) && ! $this->step() ) {
+            while ( $this->state->stack_of_open_elements->pop() ) {
+                continue;
+            }
+        }
+
+        $this->current_element = array_shift( $this->element_queue );
+        while ( isset( $this->context_node ) && ! $this->has_seen_context_node ) {
+            if ( isset( $this->current_element ) ) {
+                if ( $this->context_node === $this->current_element->token && WP_HTML_Stack_Event::PUSH === $this->current_element->operation ) {
+                    $this->has_seen_context_node = true;
+                    return $this->next_token();
+                }
+            }
+            $this->current_element = array_shift( $this->element_queue );
+        }
+
+        if ( ! isset( $this->current_element ) ) {
+            return $this->next_token();
+        }
+
+        if ( isset( $this->context_node ) && WP_HTML_Stack_Event::POP === $this->current_element->operation && $this->context_node === $this->current_element->token ) {
+            $this->element_queue   = array();
+            $this->current_element = null;
+            return false;
+        }
+
+        // Avoid sending close events for elements which don't expect a closing.
+        if (
+            WP_HTML_Stack_Event::POP === $this->current_element->operation &&
+            ! static::expects_closer( $this->current_element->token->node_name )
+        ) {
+            return $this->next_token();
+        }
+
+        return true;
+    }
+
+
+    /**
+     * Indicates if the current tag token is a tag closer.
+     *
+     * Example:
+     *
+     *     $p = WP_HTML_Processor::create_fragment( '<div></div>' );
+     *     $p->next_tag( array( 'tag_name' => 'div', 'tag_closers' => 'visit' ) );
+     *     $p->is_tag_closer() === false;
+     *
+     *     $p->next_tag( array( 'tag_name' => 'div', 'tag_closers' => 'visit' ) );
+     *     $p->is_tag_closer() === true;
+     *
+     * @since 6.6.0 Subclassed for HTML Processor.
+     *
+     * @return bool Whether the current tag is a tag closer.
+     */
+    public function is_tag_closer() {
+        return isset( $this->current_element )
+            ? ( WP_HTML_Stack_Event::POP === $this->current_element->operation )
+            : parent::is_tag_closer();
     }
 
@@ -526 +644 @@
      *       SVG and MathML namespace.
      *
+
      * @return bool Whether to expect a closer for the currently-matched node,
      *              or `null` if not matched on any token.
      */
-    public function expects_closer() {
-        $token_name = $this->get_token_name();
+    public function expects_closer() {
+        $token_name = $this->get_token_name();
         if ( ! isset( $token_name ) ) {
             return null;
@@ -582 +701 @@
              */
             $top_node = $this->state->stack_of_open_elements->current_node();
-            if (
-                $top_node && (
-                    // Void elements.
-                    self::is_void( $top_node->node_name ) ||
-                    // Comments, text nodes, and other atomic tokens.
-                    '#' === $top_node->node_name[0] ||
-                    // Doctype declarations.
-                    'html' === $top_node->node_name
-                )
-            ) {
+            if ( isset( $top_node ) && ! static::expects_closer( $top_node ) ) {
                 $this->state->stack_of_open_elements->pop();
             }
@@ -651 +761 @@
      * @since 6.4.0
      *
+
+
      * @return string[]|null Array of tag names representing path to matched node, if matched, otherwise NULL.
      */
@@ -709 +821 @@
         $token_name = $this->get_token_name();
         $token_type = $this->get_token_type();
-        $op_sigil   = '#tag' === $token_type ? ( $this->is_tag_closer() ? '-' : '+' ) : '';
+        $op_sigil   = '#tag' === $token_type ? ( is_tag_closer() ? '-' : '+' ) : '';
         $op         = "{$op_sigil}{$token_name}";
 
@@ -1232 +1344 @@
         }
 
-        if ( ! $this->is_tag_closer() ) {
+        if ( ! is_tag_closer() ) {
             /*
              * > Any other start tag
@@ -1326 +1438 @@
         if ( null !== $this->last_error ) {
             return null;
+
+
+
+
         }
 
@@ -1344 +1460 @@
 
     /**
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
      * Removes a bookmark that is no longer needed.
      *
@@ -1384 +1683 @@
             : 0;
         $bookmark_starts_at   = $this->bookmarks[ $actual_bookmark_name ]->start;
+
         $direction            = $bookmark_starts_at > $processor_started_at ? 'forward' : 'backward';
 
@@ -1439 +1739 @@
             $this->state->insertion_mode = WP_HTML_Processor_State::INSERTION_MODE_IN_BODY;
             $this->state->frameset_ok    = true;
+
+
         }
 
@@ -1446 +1748 @@
         }
 
-        while ( $this->step() ) {
+        while ( $this->() ) {
             if ( $bookmark_starts_at === $this->bookmarks[ $this->state->current_token->bookmark_name ]->start ) {
+
+
+
                 return true;
             }

trunk/src/wp-settings.php

@@ -260 +260 @@
 require ABSPATH . WPINC . '/html-api/class-wp-html-open-elements.php';
 require ABSPATH . WPINC . '/html-api/class-wp-html-token.php';
+
 require ABSPATH . WPINC . '/html-api/class-wp-html-processor-state.php';
 require ABSPATH . WPINC . '/html-api/class-wp-html-processor.php';

trunk/tests/phpunit/tests/html-api/wpHtmlProcessorBreadcrumbs.php

@@ -232 +232 @@
         $processor = WP_HTML_Processor::create_fragment( $html );
 
-        while ( $processor->step() && null === $processor->get_attribute( 'supported' ) ) {
+        while ( $processor->() && null === $processor->get_attribute( 'supported' ) ) {
             continue;
         }
 
+
+
+
+
+
         $this->assertTrue( $processor->get_attribute( 'supported' ), 'Did not find required supported element.' );
-        $this->assertFalse( $processor->step(), "Didn't properly reject unsupported markup: {$description}" );
+        $processor->next_token();
+        $this->assertNotNull( $processor->get_last_error(), "Didn't properly reject unsupported markup: {$description}" );
     }
 
@@ -248 +254 @@
         return array(
             'A with formatting following unclosed A' => array(
-                '<a><strong>Click <a supported><big unsupported>Here</big></a></strong></a>',
+                '<a><strong>Click <>Here</big></a></strong></a>',
                 'Unclosed formatting requires complicated reconstruction.',
             ),
@@ -326 +332 @@
             'EM inside DIV'                         => array( '<div>The weather is <em target>beautiful</em>.</div>', array( 'HTML', 'BODY', 'DIV', 'EM' ), 1 ),
             'EM after closed EM'                    => array( '<em></em><em target></em>', array( 'HTML', 'BODY', 'EM' ), 2 ),
-            'EM after closed EMs'                   => array( '<em></em><em><em></em></em><em></em><em></em><em target></em>', array( 'HTML', 'BODY', 'EM' ), 6 ),
+            'EM after closed EMs'                   => array( '<em></em><em><em></em></em><em></em><em></em><em target></em>', array( 'HTML', 'BODY', 'EM' ),  ),
             'EM after unclosed EM'                  => array( '<em><em target></em>', array( 'HTML', 'BODY', 'EM', 'EM' ), 1 ),
             'EM after unclosed EM after DIV'        => array( '<em><div><em target>', array( 'HTML', 'BODY', 'EM', 'DIV', 'EM' ), 1 ),

trunk/tests/phpunit/tests/html-api/wpHtmlProcessorSemanticRules.php

@@ -388 +388 @@
         $this->assertSame( array( 'HTML', 'BODY', 'DIV', 'SPAN', 'CODE' ), $processor->get_breadcrumbs(), 'Failed to produce expected DOM nesting.' );
 
-        $this->assertTrue( $processor->step(), 'Failed to advance past CODE tag to expected SPAN closer.' );
+        $this->assertTrue( $processor->(), 'Failed to advance past CODE tag to expected SPAN closer.' );
         $this->assertTrue( $processor->is_tag_closer(), 'Expected to find closing SPAN, but found opener instead.' );
         $this->assertSame( array( 'HTML', 'BODY', 'DIV' ), $processor->get_breadcrumbs(), 'Failed to advance past CODE tag to expected DIV opener.' );