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

Timestamp:

05/23/2024 11:35:52 PM (9 months ago)

Author:

dmsnell

Message:

HTML API: Add method to report depth of currently-matched node.

The HTML Processor maintains a stack of open elements, where every element,
every #text node, every HTML comment, and other node is pushed and popped while
traversing the document. The "depth" of each of these nodes represents how deep
that stack is where the node appears. Unfortunately this information isn't
exposed to calling code, which has led different projects to attempt to
calculate this value externally. This isn't always trivial, but the HTML
Processor could make it so by exposing the internal knowledge in a new method.

In this patch the get_current_depth() method returns just that. Since the
processor always exists within a context, the depth includes nesting from the
always-present html element and also the body, since currently the HTML
Processor only supports parsing in the IN BODY context.

This means that the depth reported for the DIV in <div> is 3, not 1, because
its breadcrumbs path is HTML > BODY > DIV.

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

Fixes #61255.
Props dmsnell, jonsurrell.

File:

• trunk/src/wp-includes/html-api/class-wp-html-processor.php (modified) (1 diff)

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

@@ -622 +622 @@
 
         return $breadcrumbs;
+    }
+
+    /**
+     * Returns the nesting depth of the current location in the document.
+     *
+     * Example:
+     *
+     *     $processor = WP_HTML_Processor::create_fragment( '<div><p></p></div>' );
+     *     // The processor starts in the BODY context, meaning it has depth from the start: HTML > BODY.
+     *     2 === $processor->get_current_depth();
+     *
+     *     // Opening the DIV element increases the depth.
+     *     $processor->next_token();
+     *     3 === $processor->get_current_depth();
+     *
+     *     // Opening the P element increases the depth.
+     *     $processor->next_token();
+     *     4 === $processor->get_current_depth();
+     *
+     *     // The P element is closed during `next_token()` so the depth is decreased to reflect that.
+     *     $processor->next_token();
+     *     3 === $processor->get_current_depth();
+     *
+     * @since 6.6.0
+     *
+     * @return int Nesting-depth of current location in the document.
+     */
+    public function get_current_depth() {
+        return $this->state->stack_of_open_elements->count();
     }