WP_HTML_Processor::next_tag │ public │ WP 6.4.0

Finds the next tag matching the $query.

Method of the class: WP_HTML_Processor{}

No Hooks.

Returns

true|false. Whether a tag was matched.

Usage

$WP_HTML_Processor = new WP_HTML_Processor();
$WP_HTML_Processor->next_tag( $query ): bool;

$query(array|string|null)

Which tag name to find, having which class, etc.

Default: 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.
  Default: 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', '*' ).

Changelog

WP_HTML_Processor::next_tag() WP HTML Processor::next tag code ^{WP 6.9}

public function next_tag( $query = null ): bool {
	$visit_closers = isset( $query['tag_closers'] ) && 'visit' === $query['tag_closers'];

	if ( null === $query ) {
		while ( $this->next_token() ) {
			if ( '#tag' !== $this->get_token_type() ) {
				continue;
			}

			if ( ! $this->is_tag_closer() || $visit_closers ) {
				return true;
			}
		}

		return false;
	}

	if ( is_string( $query ) ) {
		$query = array( 'breadcrumbs' => array( $query ) );
	}

	if ( ! is_array( $query ) ) {
		_doing_it_wrong(
			__METHOD__,
			__( 'Please pass a query array to this function.' ),
			'6.4.0'
		);
		return false;
	}

	if ( isset( $query['tag_name'] ) ) {
		$query['tag_name'] = strtoupper( $query['tag_name'] );
	}

	$needs_class = ( isset( $query['class_name'] ) && is_string( $query['class_name'] ) )
		? $query['class_name']
		: null;

	if ( ! ( array_key_exists( 'breadcrumbs', $query ) && is_array( $query['breadcrumbs'] ) ) ) {
		while ( $this->next_token() ) {
			if ( '#tag' !== $this->get_token_type() ) {
				continue;
			}

			if ( isset( $query['tag_name'] ) && $query['tag_name'] !== $this->get_token_name() ) {
				continue;
			}

			if ( isset( $needs_class ) && ! $this->has_class( $needs_class ) ) {
				continue;
			}

			if ( ! $this->is_tag_closer() || $visit_closers ) {
				return true;
			}
		}

		return false;
	}

	$breadcrumbs  = $query['breadcrumbs'];
	$match_offset = isset( $query['match_offset'] ) ? (int) $query['match_offset'] : 1;

	while ( $match_offset > 0 && $this->next_token() ) {
		if ( '#tag' !== $this->get_token_type() || $this->is_tag_closer() ) {
			continue;
		}

		if ( isset( $needs_class ) && ! $this->has_class( $needs_class ) ) {
			continue;
		}

		if ( $this->matches_breadcrumbs( $breadcrumbs ) && 0 === --$match_offset ) {
			return true;
		}
	}

	return false;
}