th_to_index_block_template ) && is_readable( $path_to_index_block_template ) ) {
$this->block_theme = true;
break;
}
}
return $this->block_theme;
}
/**
* Retrieves the path of a file in the theme.
*
* Searches in the stylesheet directory before the template directory so themes
* which inherit from a parent theme can just override one file.
*
* @since 5.9.0
*
* @param string $file Optional. File to search for in the stylesheet directory.
* @return string The path of the file.
*/
public function get_file_path( $file = '' ) {
$file = ltrim( $file, '/' );
$stylesheet_directory = $this->get_stylesheet_directory();
$template_directory = $this->get_template_directory();
if ( empty( $file ) ) {
$path = $stylesheet_directory;
} elseif ( $stylesheet_directory !== $template_directory && file_exists( $stylesheet_directory . '/' . $file ) ) {
$path = $stylesheet_directory . '/' . $file;
} else {
$path = $template_directory . '/' . $file;
}
/** This filter is documented in wp-includes/link-template.php */
return apply_filters( 'theme_file_path', $path, $file );
}
/**
* Determines the latest WordPress default theme that is installed.
*
* This hits the filesystem.
*
* @since 4.4.0
*
* @return WP_Theme|false Object, or false if no theme is installed, which would be bad.
*/
public static function get_core_default_theme() {
foreach ( array_reverse( self::$default_themes ) as $slug => $name ) {
$theme = wp_get_theme( $slug );
if ( $theme->exists() ) {
return $theme;
}
}
return false;
}
/**
* Returns array of stylesheet names of themes allowed on the site or network.
*
* @since 3.4.0
*
* @param int $blog_id Optional. ID of the site. Defaults to the current site.
* @return string[] Array of stylesheet names.
*/
public static function get_allowed( $blog_id = null ) {
/**
* Filters the array of themes allowed on the network.
*
* Site is provided as context so that a list of network allowed themes can
* be filtered further.
*
* @since 4.5.0
*
* @param string[] $allowed_themes An array of theme stylesheet names.
* @param int $blog_id ID of the site.
*/
$network = (array) apply_filters( 'network_allowed_themes', self::get_allowed_on_network(), $blog_id );
return $network + self::get_allowed_on_site( $blog_id );
}
/**
* Returns array of stylesheet names of themes allowed on the network.
*
* @since 3.4.0
*
* @return string[] Array of stylesheet names.
*/
public static function get_allowed_on_network() {
static $allowed_themes;
if ( ! isset( $allowed_themes ) ) {
$allowed_themes = (array) get_site_option( 'allowedthemes' );
}
/**
* Filters the array of themes allowed on the network.
*
* @since MU (3.0.0)
*
* @param string[] $allowed_themes An array of theme stylesheet names.
*/
$allowed_themes = apply_filters( 'allowed_themes', $allowed_themes );
return $allowed_themes;
}
/**
* Returns array of stylesheet names of themes allowed on the site.
*
* @since 3.4.0
*
* @param int $blog_id Optional. ID of the site. Defaults to the current site.
* @return string[] Array of stylesheet names.
*/
public static function get_allowed_on_site( $blog_id = null ) {
static $allowed_themes = array();
if ( ! $blog_id || ! is_multisite() ) {
$blog_id = get_current_blog_id();
}
if ( isset( $allowed_themes[ $blog_id ] ) ) {
/**
* Filters the array of themes allowed on the site.
*
* @since 4.5.0
*
* @param string[] $allowed_themes An array of theme stylesheet names.
* @param int $blog_id ID of the site. Defaults to current site.
*/
return (array) apply_filters( 'site_allowed_themes', $allowed_themes[ $blog_id ], $blog_id );
}
$current = get_current_blog_id() == $blog_id;
if ( $current ) {
$allowed_themes[ $blog_id ] = get_option( 'allowedthemes' );
} else {
switch_to_blog( $blog_id );
$allowed_themes[ $blog_id ] = get_option( 'allowedthemes' );
restore_current_blog();
}
/*
* This is all super old MU back compat joy.
* 'allowedthemes' keys things by stylesheet. 'allowed_themes' keyed things by name.
*/
if ( false === $allowed_themes[ $blog_id ] ) {
if ( $current ) {
$allowed_themes[ $blog_id ] = get_option( 'allowed_themes' );
} else {
switch_to_blog( $blog_id );
$allowed_themes[ $blog_id ] = get_option( 'allowed_themes' );
restore_current_blog();
}
if ( ! is_array( $allowed_themes[ $blog_id ] ) || empty( $allowed_themes[ $blog_id ] ) ) {
$allowed_themes[ $blog_id ] = array();
} else {
$converted = array();
$themes = wp_get_themes();
foreach ( $themes as $stylesheet => $theme_data ) {
if ( isset( $allowed_themes[ $blog_id ][ $theme_data->get( 'Name' ) ] ) ) {
$converted[ $stylesheet ] = true;
}
}
$allowed_themes[ $blog_id ] = $converted;
}
// Set the option so we never have to go through this pain again.
if ( is_admin() && $allowed_themes[ $blog_id ] ) {
if ( $current ) {
update_option( 'allowedthemes', $allowed_themes[ $blog_id ] );
delete_option( 'allowed_themes' );
} else {
switch_to_blog( $blog_id );
update_option( 'allowedthemes', $allowed_themes[ $blog_id ] );
delete_option( 'allowed_themes' );
restore_current_blog();
}
}
}
/** This filter is documented in wp-includes/class-wp-theme.php */
return (array) apply_filters( 'site_allowed_themes', $allowed_themes[ $blog_id ], $blog_id );
}
/**
* Returns the folder names of the block template directories.
*
* @since 6.4.0
*
* @return string[] {
* Folder names used by block themes.
*
* @type string $wp_template Theme-relative directory name for block templates.
* @type string $wp_template_part Theme-relative directory name for block template parts.
* }
*/
public function get_block_template_folders() {
// Return set/cached value if available.
if ( isset( $this->block_template_folders ) ) {
return $this->block_template_folders;
}
$this->block_template_folders = $this->default_template_folders;
$stylesheet_directory = $this->get_stylesheet_directory();
// If the theme uses deprecated block template folders.
if ( file_exists( $stylesheet_directory . '/block-templates' ) || file_exists( $stylesheet_directory . '/block-template-parts' ) ) {
$this->block_template_folders = array(
'wp_template' => 'block-templates',
'wp_template_part' => 'block-template-parts',
);
}
return $this->block_template_folders;
}
/**
* Gets block pattern data for a specified theme.
* Each pattern is defined as a PHP file and defines
* its metadata using plugin-style headers. The minimum required definition is:
*
* /**
* * Title: My Pattern
* * Slug: my-theme/my-pattern
* *
*
* The output of the PHP source corresponds to the content of the pattern, e.g.:
*
* Hello
*
* If applicable, this will collect from both parent and child theme.
*
* Other settable fields include:
*
* - Description
* - Viewport Width
* - Inserter (yes/no)
* - Categories (comma-separated values)
* - Keywords (comma-separated values)
* - Block Types (comma-separated values)
* - Post Types (comma-separated values)
* - Template Types (comma-separated values)
*
* @since 6.4.0
*
* @return array Block pattern data.
*/
public function get_block_patterns() {
$can_use_cached = ! wp_is_development_mode( 'theme' );
$pattern_data = $this->get_pattern_cache();
if ( is_array( $pattern_data ) ) {
if ( $can_use_cached ) {
return $pattern_data;
}
// If in development mode, clear pattern cache.
$this->delete_pattern_cache();
}
$dirpath = $this->get_stylesheet_directory() . '/patterns/';
$pattern_data = array();
if ( ! file_exists( $dirpath ) ) {
if ( $can_use_cached ) {
$this->set_pattern_cache( $pattern_data );
}
return $pattern_data;
}
$files = glob( $dirpath . '*.php' );
if ( ! $files ) {
if ( $can_use_cached ) {
$this->set_pattern_cache( $pattern_data );
}
return $pattern_data;
}
$default_headers = array(
'title' => 'Title',
'slug' => 'Slug',
'description' => 'Description',
'viewportWidth' => 'Viewport Width',
'inserter' => 'Inserter',
'categories' => 'Categories',
'keywords' => 'Keywords',
'blockTypes' => 'Block Types',
'postTypes' => 'Post Types',
'templateTypes' => 'Template Types',
);
$properties_to_parse = array(
'categories',
'keywords',
'blockTypes',
'postTypes',
'templateTypes',
);
foreach ( $files as $file ) {
$pattern = get_file_data( $file, $default_headers );
if ( empty( $pattern['slug'] ) ) {
_doing_it_wrong(
__FUNCTION__,
sprintf(
/* translators: 1: file name. */
__( 'Could not register file "%s" as a block pattern ("Slug" field missing)' ),
$file
),
'6.0.0'
);
continue;
}
if ( ! preg_match( '/^[A-z0-9\/_-]+$/', $pattern['slug'] ) ) {
_doing_it_wrong(
__FUNCTION__,
sprintf(
/* translators: 1: file name; 2: slug value found. */
__( 'Could not register file "%1$s" as a block pattern (invalid slug "%2$s")' ),
$file,
$pattern['slug']
),
'6.0.0'
);
}
// Title is a required property.
if ( ! $pattern['title'] ) {
_doing_it_wrong(
__FUNCTION__,
sprintf(
/* translators: 1: file name. */
__( 'Could not register file "%s" as a block pattern ("Title" field missing)' ),
$file
),
'6.0.0'
);
continue;
}
// For properties of type array, parse data as comma-separated.
foreach ( $properties_to_parse as $property ) {
if ( ! empty( $pattern[ $property ] ) ) {
$pattern[ $property ] = array_filter( wp_parse_list( (string) $pattern[ $property ] ) );
} else {
unset( $pattern[ $property ] );
}
}
// Parse properties of type int.
$property = 'viewportWidth';
if ( ! empty( $pattern[ $property ] ) ) {
$pattern[ $property ] = (int) $pattern[ $property ];
} else {
unset( $pattern[ $property ] );
}
// Parse properties of type bool.
$property = 'inserter';
if ( ! empty( $pattern[ $property ] ) ) {
$pattern[ $property ] = in_array(
strtolower( $pattern[ $property ] ),
array( 'yes', 'true' ),
true
);
} else {
unset( $pattern[ $property ] );
}
$key = str_replace( $dirpath, '', $file );
$pattern_data[ $key ] = $pattern;
}
if ( $can_use_cached ) {
$this->set_pattern_cache( $pattern_data );
}
return $pattern_data;
}
/**
* Gets block pattern cache.
*
* @since 6.4.0
*
* @return array|false Returns an array of patterns if cache is found, otherwise false.
*/
private function get_pattern_cache() {
if ( ! $this->exists() ) {
return false;
}
$pattern_data = wp_cache_get( 'wp_theme_patterns_' . $this->stylesheet );
if ( is_array( $pattern_data ) && $pattern_data['version'] === $this->get( 'Version' ) ) {
return $pattern_data['patterns'];
}
return false;
}
/**
* Sets block pattern cache.
*
* @since 6.4.0
*
* @param array $patterns Block patterns data to set in cache.
*/
private function set_pattern_cache( array $patterns ) {
$pattern_data = array(
'version' => $this->get( 'Version' ),
'patterns' => $patterns,
);
wp_cache_set( 'wp_theme_patterns_' . $this->stylesheet, $pattern_data );
}
/**
* Clears block pattern cache.
*
* @since 6.4.0
*/
public function delete_pattern_cache() {
wp_cache_delete( 'wp_theme_patterns_' . $this->stylesheet );
}
/**
* Enables a theme for all sites on the current network.
*
* @since 4.6.0
*
* @param string|string[] $stylesheets Stylesheet name or array of stylesheet names.
*/
public static function network_enable_theme( $stylesheets ) {
if ( ! is_multisite() ) {
return;
}
if ( ! is_array( $stylesheets ) ) {
$stylesheets = array( $stylesheets );
}
$allowed_themes = get_site_option( 'allowedthemes' );
foreach ( $stylesheets as $stylesheet ) {
$allowed_themes[ $stylesheet ] = true;
}
update_site_option( 'allowedthemes', $allowed_themes );
}
/**
* Disables a theme for all sites on the current network.
*
* @since 4.6.0
*
* @param string|string[] $stylesheets Stylesheet name or array of stylesheet names.
*/
public static function network_disable_theme( $stylesheets ) {
if ( ! is_multisite() ) {
return;
}
if ( ! is_array( $stylesheets ) ) {
$stylesheets = array( $stylesheets );
}
$allowed_themes = get_site_option( 'allowedthemes' );
foreach ( $stylesheets as $stylesheet ) {
if ( isset( $allowed_themes[ $stylesheet ] ) ) {
unset( $allowed_themes[ $stylesheet ] );
}
}
update_site_option( 'allowedthemes', $allowed_themes );
}
/**
* Sorts themes by name.
*
* @since 3.4.0
*
* @param WP_Theme[] $themes Array of theme objects to sort (passed by reference).
*/
public static function sort_by_name( &$themes ) {
if ( str_starts_with( get_user_locale(), 'en_' ) ) {
uasort( $themes, array( 'WP_Theme', '_name_sort' ) );
} else {
foreach ( $themes as $key => $theme ) {
$theme->translate_header( 'Name', $theme->headers['Name'] );
}
uasort( $themes, array( 'WP_Theme', '_name_sort_i18n' ) );
}
}
/**
* Callback function for usort() to naturally sort themes by name.
*
* Accesses the Name header directly from the class for maximum speed.
* Would choke on HTML but we don't care enough to slow it down with strip_tags().
*
* @since 3.4.0
*
* @param WP_Theme $a First theme.
* @param WP_Theme $b Second theme.
* @return int Negative if `$a` falls lower in the natural order than `$b`. Zero if they fall equally.
* Greater than 0 if `$a` falls higher in the natural order than `$b`. Used with usort().
*/
private static function _name_sort( $a, $b ) {
return strnatcasecmp( $a->headers['Name'], $b->headers['Name'] );
}
/**
* Callback function for usort() to naturally sort themes by translated name.
*
* @since 3.4.0
*
* @param WP_Theme $a First theme.
* @param WP_Theme $b Second theme.
* @return int Negative if `$a` falls lower in the natural order than `$b`. Zero if they fall equally.
* Greater than 0 if `$a` falls higher in the natural order than `$b`. Used with usort().
*/
private static function _name_sort_i18n( $a, $b ) {
return strnatcasecmp( $a->name_translated, $b->name_translated );
}
private static function _check_headers_property_has_correct_type( $headers ) {
if ( ! is_array( $headers ) ) {
return false;
}
foreach ( $headers as $key => $value ) {
if ( ! is_string( $key ) || ! is_string( $value ) ) {
return false;
}
}
return true;
}
}
multiple calls with case-variant attribute names.
*
* @param string $name The attribute name to target.
* @param string|bool $value The new attribute value.
* @return bool Whether an attribute value was set.
*/
public function set_attribute( $name, $value ) {
if ( $this->is_closing_tag || null === $this->tag_name_starts_at ) {
return false;
}
/*
* WordPress rejects more characters than are strictly forbidden
* in HTML5. This is to prevent additional security risks deeper
* in the WordPress and plugin stack. Specifically the
* less-than (<) greater-than (>) and ampersand (&) aren't allowed.
*
* The use of a PCRE match enables looking for specific Unicode
* code points without writing a UTF-8 decoder. Whereas scanning
* for one-byte characters is trivial (with `strcspn`), scanning
* for the longer byte sequences would be more complicated. Given
* that this shouldn't be in the hot path for execution, it's a
* reasonable compromise in efficiency without introducing a
* noticeable impact on the overall system.
*
* @see https://html.spec.whatwg.org/#attributes-2
*
* @TODO as the only regex pattern maybe we should take it out? are
* Unicode patterns available broadly in Core?
*/
if ( preg_match(
'~[' .
// Syntax-like characters.
'"\'>& =' .
// Control characters.
'\x{00}-\x{1F}' .
// HTML noncharacters.
'\x{FDD0}-\x{FDEF}' .
'\x{FFFE}\x{FFFF}\x{1FFFE}\x{1FFFF}\x{2FFFE}\x{2FFFF}\x{3FFFE}\x{3FFFF}' .
'\x{4FFFE}\x{4FFFF}\x{5FFFE}\x{5FFFF}\x{6FFFE}\x{6FFFF}\x{7FFFE}\x{7FFFF}' .
'\x{8FFFE}\x{8FFFF}\x{9FFFE}\x{9FFFF}\x{AFFFE}\x{AFFFF}\x{BFFFE}\x{BFFFF}' .
'\x{CFFFE}\x{CFFFF}\x{DFFFE}\x{DFFFF}\x{EFFFE}\x{EFFFF}\x{FFFFE}\x{FFFFF}' .
'\x{10FFFE}\x{10FFFF}' .
']~Ssu',
$name
) ) {
_doing_it_wrong(
__METHOD__,
__( 'Invalid attribute name.' ),
'6.2.0'
);
return false;
}
/*
* > The values "true" and "false" are not allowed on boolean attributes.
* > To represent a false value, the attribute has to be omitted altogether.
* - HTML5 spec, https://html.spec.whatwg.org/#boolean-attributes
*/
if ( false === $value ) {
return $this->remove_attribute( $name );
}
if ( true === $value ) {
$updated_attribute = $name;
} else {
$escaped_new_value = esc_attr( $value );
$updated_attribute = "{$name}=\"{$escaped_new_value}\"";
}
/*
* > There must never be two or more attributes on
* > the same start tag whose names are an ASCII
* > case-insensitive match for each other.
* - HTML 5 spec
*
* @see https://html.spec.whatwg.org/multipage/syntax.html#attributes-2:ascii-case-insensitive
*/
$comparable_name = strtolower( $name );
if ( isset( $this->attributes[ $comparable_name ] ) ) {
/*
* Update an existing attribute.
*
* Example – set attribute id to "new" in
:
*
*
* ^-------------^
* start end
* replacement: `id="new"`
*
* Result:
*/
$existing_attribute = $this->attributes[ $comparable_name ];
$this->lexical_updates[ $comparable_name ] = new WP_HTML_Text_Replacement(
$existing_attribute->start,
$existing_attribute->end,
$updated_attribute
);
} else {
/*
* Create a new attribute at the tag's name end.
*
* Example – add attribute id="new" to :
*
*
* ^
* start and end
* replacement: ` id="new"`
*
* Result:
*/
$this->lexical_updates[ $comparable_name ] = new WP_HTML_Text_Replacement(
$this->tag_name_starts_at + $this->tag_name_length,
$this->tag_name_starts_at + $this->tag_name_length,
' ' . $updated_attribute
);
}
/*
* Any calls to update the `class` attribute directly should wipe out any
* enqueued class changes from `add_class` and `remove_class`.
*/
if ( 'class' === $comparable_name && ! empty( $this->classname_updates ) ) {
$this->classname_updates = array();
}
return true;
}
/**
* Remove an attribute from the currently-matched tag.
*
* @since 6.2.0
*
* @param string $name The attribute name to remove.
* @return bool Whether an attribute was removed.
*/
public function remove_attribute( $name ) {
if ( $this->is_closing_tag ) {
return false;
}
/*
* > There must never be two or more attributes on
* > the same start tag whose names are an ASCII
* > case-insensitive match for each other.
* - HTML 5 spec
*
* @see https://html.spec.whatwg.org/multipage/syntax.html#attributes-2:ascii-case-insensitive
*/
$name = strtolower( $name );
/*
* Any calls to update the `class` attribute directly should wipe out any
* enqueued class changes from `add_class` and `remove_class`.
*/
if ( 'class' === $name && count( $this->classname_updates ) !== 0 ) {
$this->classname_updates = array();
}
/*
* If updating an attribute that didn't exist in the input
* document, then remove the enqueued update and move on.
*
* For example, this might occur when calling `remove_attribute()`
* after calling `set_attribute()` for the same attribute
* and when that attribute wasn't originally present.
*/
if ( ! isset( $this->attributes[ $name ] ) ) {
if ( isset( $this->lexical_updates[ $name ] ) ) {
unset( $this->lexical_updates[ $name ] );
}
return false;
}
/*
* Removes an existing tag attribute.
*
* Example – remove the attribute id from :
*
* ^-------------^
* start end
* replacement: ``
*
* Result:
*/
$this->lexical_updates[ $name ] = new WP_HTML_Text_Replacement(
$this->attributes[ $name ]->start,
$this->attributes[ $name ]->end,
''
);
// Removes any duplicated attributes if they were also present.
if ( null !== $this->duplicate_attributes && array_key_exists( $name, $this->duplicate_attributes ) ) {
foreach ( $this->duplicate_attributes[ $name ] as $attribute_token ) {
$this->lexical_updates[] = new WP_HTML_Text_Replacement(
$attribute_token->start,
$attribute_token->end,
''
);
}
}
return true;
}
/**
* Adds a new class name to the currently matched tag.
*
* @since 6.2.0
*
* @param string $class_name The class name to add.
* @return bool Whether the class was set to be added.
*/
public function add_class( $class_name ) {
if ( $this->is_closing_tag ) {
return false;
}
if ( null !== $this->tag_name_starts_at ) {
$this->classname_updates[ $class_name ] = self::ADD_CLASS;
}
return true;
}
/**
* Removes a class name from the currently matched tag.
*
* @since 6.2.0
*
* @param string $class_name The class name to remove.
* @return bool Whether the class was set to be removed.
*/
public function remove_class( $class_name ) {
if ( $this->is_closing_tag ) {
return false;
}
if ( null !== $this->tag_name_starts_at ) {
$this->classname_updates[ $class_name ] = self::REMOVE_CLASS;
}
return true;
}
/**
* Returns the string representation of the HTML Tag Processor.
*
* @since 6.2.0
*
* @see WP_HTML_Tag_Processor::get_updated_html()
*
* @return string The processed HTML.
*/
public function __toString() {
return $this->get_updated_html();
}
/**
* Returns the string representation of the HTML Tag Processor.
*
* @since 6.2.0
* @since 6.2.1 Shifts the internal cursor corresponding to the applied updates.
* @since 6.4.0 No longer calls subclass method `next_tag()` after updating HTML.
*
* @return string The processed HTML.
*/
public function get_updated_html() {
$requires_no_updating = 0 === count( $this->classname_updates ) && 0 === count( $this->lexical_updates );
/*
* When there is nothing more to update and nothing has already been
* updated, return the original document and avoid a string copy.
*/
if ( $requires_no_updating ) {
return $this->html;
}
/*
* Keep track of the position right before the current tag. This will
* be necessary for reparsing the current tag after updating the HTML.
*/
$before_current_tag = $this->tag_name_starts_at - 1;
/*
* 1. Apply the enqueued edits and update all the pointers to reflect those changes.
*/
$this->class_name_updates_to_attributes_updates();
$before_current_tag += $this->apply_attributes_updates( $before_current_tag );
/*
* 2. Rewind to before the current tag and reparse to get updated attributes.
*
* At this point the internal cursor points to the end of the tag name.
* Rewind before the tag name starts so that it's as if the cursor didn't
* move; a call to `next_tag()` will reparse the recently-updated attributes
* and additional calls to modify the attributes will apply at this same
* location, but in order to avoid issues with subclasses that might add
* behaviors to `next_tag()`, the internal methods should be called here
* instead.
*
* It's important to note that in this specific place there will be no change
* because the processor was already at a tag when this was called and it's
* rewinding only to the beginning of this very tag before reprocessing it
* and its attributes.
*
* Previous HTMLMore HTML
* ↑ │ back up by the length of the tag name plus the opening <
* └←─┘ back up by strlen("em") + 1 ==> 3
*/
$this->bytes_already_parsed = $before_current_tag;
$this->parse_next_tag();
// Reparse the attributes.
while ( $this->parse_next_attribute() ) {
continue;
}
$tag_ends_at = strpos( $this->html, '>', $this->bytes_already_parsed );
$this->tag_ends_at = $tag_ends_at;
$this->bytes_already_parsed = $tag_ends_at;
return $this->html;
}
/**
* Parses tag query input into internal search criteria.
*
* @since 6.2.0
*
* @param array|string|null $query {
* Optional. Which tag name to find, having which class, etc. Default is to find any tag.
*
* @type string|null $tag_name Which tag to find, or `null` for "any tag."
* @type int|null $match_offset Find the Nth tag matching all search criteria.
* 1 for "first" tag, 3 for "third," etc.
* Defaults to first tag.
* @type string|null $class_name Tag must contain this class name to match.
* @type string $tag_closers "visit" or "skip": whether to stop on tag closers, e.g. .
* }
*/
private function parse_query( $query ) {
if ( null !== $query && $query === $this->last_query ) {
return;
}
$this->last_query = $query;
$this->sought_tag_name = null;
$this->sought_class_name = null;
$this->sought_match_offset = 1;
$this->stop_on_tag_closers = false;
// A single string value means "find the tag of this name".
if ( is_string( $query ) ) {
$this->sought_tag_name = $query;
return;
}
// An empty query parameter applies no restrictions on the search.
if ( null === $query ) {
return;
}
// If not using the string interface, an associative array is required.
if ( ! is_array( $query ) ) {
_doing_it_wrong(
__METHOD__,
__( 'The query argument must be an array or a tag name.' ),
'6.2.0'
);
return;
}
if ( isset( $query['tag_name'] ) && is_string( $query['tag_name'] ) ) {
$this->sought_tag_name = $query['tag_name'];
}
if ( isset( $query['class_name'] ) && is_string( $query['class_name'] ) ) {
$this->sought_class_name = $query['class_name'];
}
if ( isset( $query['match_offset'] ) && is_int( $query['match_offset'] ) && 0 < $query['match_offset'] ) {
$this->sought_match_offset = $query['match_offset'];
}
if ( isset( $query['tag_closers'] ) ) {
$this->stop_on_tag_closers = 'visit' === $query['tag_closers'];
}
}
/**
* Checks whether a given tag and its attributes match the search criteria.
*
* @since 6.2.0
*
* @return bool Whether the given tag and its attribute match the search criteria.
*/
private function matches() {
if ( $this->is_closing_tag && ! $this->stop_on_tag_closers ) {
return false;
}
// Does the tag name match the requested tag name in a case-insensitive manner?
if ( null !== $this->sought_tag_name ) {
/*
* String (byte) length lookup is fast. If they aren't the
* same length then they can't be the same string values.
*/
if ( strlen( $this->sought_tag_name ) !== $this->tag_name_length ) {
return false;
}
/*
* Check each character to determine if they are the same.
* Defer calls to `strtoupper()` to avoid them when possible.
* Calling `strcasecmp()` here tested slowed than comparing each
* character, so unless benchmarks show otherwise, it should
* not be used.
*
* It's expected that most of the time that this runs, a
* lower-case tag name will be supplied and the input will
* contain lower-case tag names, thus normally bypassing
* the case comparison code.
*/
for ( $i = 0; $i < $this->tag_name_length; $i++ ) {
$html_char = $this->html[ $this->tag_name_starts_at + $i ];
$tag_char = $this->sought_tag_name[ $i ];
if ( $html_char !== $tag_char && strtoupper( $html_char ) !== $tag_char ) {
return false;
}
}
}
if ( null !== $this->sought_class_name && ! $this->has_class( $this->sought_class_name ) ) {
return false;
}
return true;
}
}