HTML API: Discourage public use of the step() method.

sirreal · sirreal · commit aa4e8ec2fe1d · 2026-06-30T17:33:15.000Z
The preferred way to iterate with `WP_HTML_Processor` is via `::next_tag()` or `::next_token()`. Developed in WordPress#12269. Props jonsurrell, dmsnell. See #64896. git-svn-id: https://develop.svn.wordpress.org/trunk@62594 602fd350-edb4-49c9-b593-d223f7449a82
diff --git a/src/wp-includes/html-api/class-wp-html-processor.php b/src/wp-includes/html-api/class-wp-html-processor.php
@@ -999,8 +999,13 @@ public function expects_closer( ?WP_HTML_Token $node = null ): ?bool {
 	/**
 	 * Steps through the HTML document and stop at the next tag, if any.
 	 *
+	 * This is an internal method. The relevant public methods are
+	 * {@see WP_HTML_Processor::next_tag()} and {@see WP_HTML_Processor::next_token()}.
+	 *
 	 * @since 6.4.0
 	 *
+	 * @access private
+	 *
 	 * @throws Exception When unable to allocate a bookmark for the next token in the input HTML document.
 	 *
 	 * @see self::PROCESS_NEXT_NODE

Original file line number	Diff line number	Diff line change
`@@ -999,8 +999,13 @@ public function expects_closer( ?WP_HTML_Token $node = null ): ?bool {`
`999`	`999`	`/**`
`1000`	`1000`	`* Steps through the HTML document and stop at the next tag, if any.`
`1001`	`1001`	`*`
	`1002`	`+ * This is an internal method. The relevant public methods are`
	`1003`	`+ * {@see WP_HTML_Processor::next_tag()} and {@see WP_HTML_Processor::next_token()}.`
	`1004`	`+ *`
`1002`	`1005`	`* @since 6.4.0`
`1003`	`1006`	`*`
	`1007`	`+ * @access private`
	`1008`	`+ *`
`1004`	`1009`	`* @throws Exception When unable to allocate a bookmark for the next token in the input HTML document.`
`1005`	`1010`	`*`
`1006`	`1011`	`* @see self::PROCESS_NEXT_NODE`