WP_HTML_Processor::next_tag( array|string|null $query = null ): bool

In this article

Finds the next tag matching the $query.

Parameters

$queryarray|string|nulloptional
Which tag name to find, having which class, etc. Default is to find any tag.
  • tag_name string|null
    Which tag to find, or null for "any tag."
  • tag_closers string
    'visit' to pause at tag closers, 'skip' or unset to only visit openers.
  • match_offset int|null
    Find the Nth tag matching all search criteria.
    1 for "first" tag, 3 for "third," etc.
    Defaults to first tag.
  • class_name string|null
    Tag must contain this whole class name to match.
  • breadcrumbs string[]
    DOM sub-path at which element is found, e.g. array( 'FIGURE', 'IMG' ).
    May also contain the wildcard * which matches a single element, e.g. array( 'SECTION', '*' ).

Default:null

Return

bool Whether a tag was matched.

Source

 *
 *     └─#text Inside TD?
 *
 * Notice that the `<td>` tags are completely ignored.
 *
 * Compare that with an SVG context node that produces the following tree:
 *
 *     ├─svg:td
 *     └─#text Inside TD?
 *
 * Here, a `td` node in the `svg` namespace is created, and its self-closing flag is respected.
 * This is a peculiarity of parsing HTML in foreign content like SVG.
 *
 * Finally, consider the tree produced with a TABLE context node:
 *
 *     └─TBODY
 *       └─TR
 *         └─TD
 *           └─#text Inside TD?
 *
 * These examples demonstrate how important the context node may be when processing an HTML
 * fragment. Special care must be taken when processing fragments that are expected to appear
 * in specific contexts. SVG and TABLE are good examples, but there are others.
 *
 * @see https://html.spec.whatwg.org/multipage/parsing.html#html-fragment-parsing-algorithm
 *
 * @since 6.8.0
 *
 * @param string $html Input HTML fragment to process.
 * @return static|null The created processor if successful, otherwise null.
 */
private function create_fragment_at_current_node( string $html ) {
	if ( $this->get_token_type() !== '#tag' || $this->is_tag_closer() ) {
		_doing_it_wrong(
			__METHOD__,
			__( 'The context element must be a start tag.' ),
			'6.8.0'
		);
		return null;
	}

	$tag_name  = $this->current_element->token->node_name;
	$namespace = $this->current_element->token->namespace;

	if ( 'html' === $namespace && self::is_void( $tag_name ) ) {
		_doing_it_wrong(
			__METHOD__,
			sprintf(
				// translators: %s: A tag name like INPUT or BR.
				__( 'The context element cannot be a void element, found "%s".' ),
				$tag_name
			),
			'6.8.0'
		);
		return null;
	}

	/*
	 * Prevent creating fragments at nodes that require a special tokenizer state.
	 * This is unsupported by the HTML Processor.
	 */
	if (
		'html' === $namespace &&
		in_array( $tag_name, array( 'IFRAME', 'NOEMBED', 'NOFRAMES', 'SCRIPT', 'STYLE', 'TEXTAREA', 'TITLE', 'XMP', 'PLAINTEXT' ), true )
	) {
		_doing_it_wrong(
			__METHOD__,
			sprintf(
				// translators: %s: A tag name like IFRAME or TEXTAREA.
				__( 'The context element "%s" is not supported.' ),
				$tag_name

Changelog

VersionDescription
6.6.0Visits all tokens, including virtual ones.
6.4.0Introduced.

User Contributed Notes

You must log in before being able to contribute a note or feedback.