HTML API: add get/set inner/outer markup

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

@@ -37,6 +37,17 @@ class WP_HTML_Open_Elements {
 	 */
 	public $stack = array();
 
+	/**
+	 * Holds functions added to be called after popping an element off the stack.
+	 *
+	 * Listeners are passed the WP_HTML_Token for the item that was removed.
+	 *
+	 * @since 6.4.0
+	 *
+	 * @var array
+	 */
+	private $after_pop_listeners = array();
+
 	/**
 	 * Whether a P element is in button scope currently.
 	 *
@@ -428,5 +439,39 @@ public function after_element_pop( $item ) {
 				$this->has_p_in_button_scope = $this->has_element_in_button_scope( 'P' );
 				break;
 		}
+
+		// Call any listeners that are registered.
+		foreach ( $this->after_pop_listeners as $listener ) {
+			call_user_func( $listener, $item );
+		}
+	}
+
+	/**
+	 * Creates a context in which a given listener is called after
+	 * popping an element off of the stack of open elements.
+	 *
+	 * It's unlikely that you will need this function. It exists
+	 * to aid an optimization in the `WP_HTML_Processor` and the
+	 * strange form of calling a generator inside a `foreach`
+	 * loop ensures that proper cleanup of the listener occurs.
+	 *
+	 * Example:
+	 *
+	 *     $did_close  = false;
+	 *     $closed_a_p = function ( $item ) use ( &$did_close ) { $did_close = 'P' === $item->node_name; };
+	 *     foreach ( $stack_of_open_elements->with_pop_listener( $closed_a_p ) ) {
+	 *         while ( ! $did_close && $processor->next_tag() ) {
+	 *             // This loop executes until _any_ P element is closed.
+	 *         }
+	 *     }
+	 *
+	 * @since 6.4.0
+	 *
+	 * @param callable $listener Called with the WP_HTML_Token for the item that was popped off of the stack.
+	 */
+	public function with_pop_listener( $listener ) {
+		$this->after_pop_listeners[] = $listener;
+		yield;
+		array_pop( $this->after_pop_listeners );
 	}
 }