' );
* false === $processor->next_tag();
* WP_HTML_Processor::ERROR_UNSUPPORTED === $processor->get_last_error();
*
* @since 6.4.0
*
* @see self::ERROR_UNSUPPORTED
* @see self::ERROR_EXCEEDED_MAX_BOOKMARKS
*
* @return string|null The last error, if one exists, otherwise null.
*/
public function get_last_error() {
return $this->last_error;
}
/**
* Finds the next tag matching the $query.
*
* @TODO: Support matching the class name and tag name.
*
* @since 6.4.0
*
* @throws Exception When unable to allocate a bookmark for the next token in the input HTML document.
*
* @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 whole class name to match.
* @type string[] $breadcrumbs 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', '*' )`.
* }
* @return bool Whether a tag was matched.
*/
public function next_tag( $query = null ) {
if ( null === $query ) {
while ( $this->step() ) {
if ( ! $this->is_tag_closer() ) {
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 ( ! ( array_key_exists( 'breadcrumbs', $query ) && is_array( $query['breadcrumbs'] ) ) ) {
while ( $this->step() ) {
if ( ! $this->is_tag_closer() ) {
return true;
}
}
return false;
}
if ( isset( $query['tag_closers'] ) && 'visit' === $query['tag_closers'] ) {
_doing_it_wrong(
__METHOD__,
__( 'Cannot visit tag closers in HTML Processor.' ),
'6.4.0'
);
return false;
}
$breadcrumbs = $query['breadcrumbs'];
$match_offset = isset( $query['match_offset'] ) ? (int) $query['match_offset'] : 1;
while ( $match_offset > 0 && $this->step() ) {
if ( $this->matches_breadcrumbs( $breadcrumbs ) && 0 === --$match_offset ) {
return true;
}
}
return false;
}
/**
* Indicates if the currently-matched tag matches the given breadcrumbs.
*
* A "*" represents a single tag wildcard, where any tag matches, but not no tags.
*
* At some point this function _may_ support a `**` syntax for matching any number
* of unspecified tags in the breadcrumb stack. This has been intentionally left
* out, however, to keep this function simple and to avoid introducing backtracking,
* which could open up surprising performance breakdowns.
*
* Example:
*
* $processor = WP_HTML_Processor::create_fragment( '' );
* $processor->next_tag( 'img' );
* true === $processor->matches_breadcrumbs( array( 'figure', 'img' ) );
* true === $processor->matches_breadcrumbs( array( 'span', 'figure', 'img' ) );
* false === $processor->matches_breadcrumbs( array( 'span', 'img' ) );
* true === $processor->matches_breadcrumbs( array( 'span', '*', 'img' ) );
*
* @since 6.4.0
*
* @param string[] $breadcrumbs 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', '*' )`.
* @return bool Whether the currently-matched tag is found at the given nested structure.
*/
public function matches_breadcrumbs( $breadcrumbs ) {
if ( ! $this->get_tag() ) {
return false;
}
// Everything matches when there are zero constraints.
if ( 0 === count( $breadcrumbs ) ) {
return true;
}
// Start at the last crumb.
$crumb = end( $breadcrumbs );
if ( '*' !== $crumb && $this->get_tag() !== strtoupper( $crumb ) ) {
return false;
}
foreach ( $this->state->stack_of_open_elements->walk_up() as $node ) {
$crumb = strtoupper( current( $breadcrumbs ) );
if ( '*' !== $crumb && $node->node_name !== $crumb ) {
return false;
}
if ( false === prev( $breadcrumbs ) ) {
return true;
}
}
return false;
}
/**
* Steps through the HTML document and stop at the next tag, if any.
*
* @since 6.4.0
*
* @throws Exception When unable to allocate a bookmark for the next token in the input HTML document.
*
* @see self::PROCESS_NEXT_NODE
* @see self::REPROCESS_CURRENT_NODE
*
* @param string $node_to_process Whether to parse the next node or reprocess the current node.
* @return bool Whether a tag was matched.
*/
public function step( $node_to_process = self::PROCESS_NEXT_NODE ) {
// Refuse to proceed if there was a previous error.
if ( null !== $this->last_error ) {
return false;
}
if ( self::PROCESS_NEXT_NODE === $node_to_process ) {
/*
* Void elements still hop onto the stack of open elements even though
* there's no corresponding closing tag. This is important for managing
* stack-based operations such as "navigate to parent node" or checking
* on an element's breadcrumbs.
*
* When moving on to the next node, therefore, if the bottom-most element
* on the stack is a void element, it must be closed.
*
* @TODO: Once self-closing foreign elements and BGSOUND are supported,
* they must also be implicitly closed here too. BGSOUND is
* special since it's only self-closing if the self-closing flag
* is provided in the opening tag, otherwise it expects a tag closer.
*/
$top_node = $this->state->stack_of_open_elements->current_node();
if ( $top_node && self::is_void( $top_node->node_name ) ) {
$this->state->stack_of_open_elements->pop();
}
parent::next_tag( self::VISIT_EVERYTHING );
}
// Finish stepping when there are no more tokens in the document.
if ( null === $this->get_tag() ) {
return false;
}
$this->state->current_token = new WP_HTML_Token(
$this->bookmark_tag(),
$this->get_tag(),
$this->is_tag_closer(),
$this->release_internal_bookmark_on_destruct
);
try {
switch ( $this->state->insertion_mode ) {
case WP_HTML_Processor_State::INSERTION_MODE_IN_BODY:
return $this->step_in_body();
default:
$this->last_error = self::ERROR_UNSUPPORTED;
throw new WP_HTML_Unsupported_Exception( "No support for parsing in the '{$this->state->insertion_mode}' state." );
}
} catch ( WP_HTML_Unsupported_Exception $e ) {
/*
* Exceptions are used in this class to escape deep call stacks that
* otherwise might involve messier calling and return conventions.
*/
return false;
}
}
/**
* Computes the HTML breadcrumbs for the currently-matched node, if matched.
*
* Breadcrumbs start at the outermost parent and descend toward the matched element.
* They always include the entire path from the root HTML node to the matched element.
*
* @TODO: It could be more efficient to expose a generator-based version of this function
* to avoid creating the array copy on tag iteration. If this is done, it would likely
* be more useful to walk up the stack when yielding instead of starting at the top.
*
* Example
*
* $processor = WP_HTML_Processor::create_fragment( '![]()
' );
* $processor->next_tag( 'IMG' );
* $processor->get_breadcrumbs() === array( 'HTML', 'BODY', 'P', 'STRONG', 'EM', 'IMG' );
*
* @since 6.4.0
*
* @return string[]|null Array of tag names representing path to matched node, if matched, otherwise NULL.
*/
public function get_breadcrumbs() {
if ( ! $this->get_tag() ) {
return null;
}
$breadcrumbs = array();
foreach ( $this->state->stack_of_open_elements->walk_down() as $stack_item ) {
$breadcrumbs[] = $stack_item->node_name;
}
return $breadcrumbs;
}
/**
* Parses next element in the 'in body' insertion mode.
*
* This internal function performs the 'in body' insertion mode
* logic for the generalized WP_HTML_Processor::step() function.
*
* @since 6.4.0
*
* @throws WP_HTML_Unsupported_Exception When encountering unsupported HTML input.
*
* @see https://html.spec.whatwg.org/#parsing-main-inbody
* @see WP_HTML_Processor::step
*
* @return bool Whether an element was found.
*/
private function step_in_body() {
$tag_name = $this->get_tag();
$op_sigil = $this->is_tag_closer() ? '-' : '+';
$op = "{$op_sigil}{$tag_name}";
switch ( $op ) {
/*
* > A start tag whose tag name is "button"
*/
case '+BUTTON':
if ( $this->state->stack_of_open_elements->has_element_in_scope( 'BUTTON' ) ) {
// @TODO: Indicate a parse error once it's possible. This error does not impact the logic here.
$this->generate_implied_end_tags();
$this->state->stack_of_open_elements->pop_until( 'BUTTON' );
}
$this->reconstruct_active_formatting_elements();
$this->insert_html_element( $this->state->current_token );
$this->state->frameset_ok = false;
return true;
/*
* > A start tag whose tag name is one of: "address", "article", "aside",
* > "blockquote", "center", "details", "dialog", "dir", "div", "dl",
* > "fieldset", "figcaption", "figure", "footer", "header", "hgroup",
* > "main", "menu", "nav", "ol", "p", "search", "section", "summary", "ul"
*/
case '+BLOCKQUOTE':
case '+DIV':
case '+FIGCAPTION':
case '+FIGURE':
case '+P':
if ( $this->state->stack_of_open_elements->has_p_in_button_scope() ) {
$this->close_a_p_element();
}
$this->insert_html_element( $this->state->current_token );
return true;
/*
* > An end tag whose tag name is one of: "address", "article", "aside", "blockquote",
* > "button", "center", "details", "dialog", "dir", "div", "dl", "fieldset",
* > "figcaption", "figure", "footer", "header", "hgroup", "listing", "main",
* > "menu", "nav", "ol", "pre", "search", "section", "summary", "ul"
*/
case '-BLOCKQUOTE':
case '-BUTTON':
case '-DIV':
case '-FIGCAPTION':
case '-FIGURE':
if ( ! $this->state->stack_of_open_elements->has_element_in_scope( $tag_name ) ) {
// @TODO: Report parse error.
// Ignore the token.
return $this->step();
}
$this->generate_implied_end_tags();
if ( $this->state->stack_of_open_elements->current_node()->node_name !== $tag_name ) {
// @TODO: Record parse error: this error doesn't impact parsing.
}
$this->state->stack_of_open_elements->pop_until( $tag_name );
return true;
/*
* > An end tag whose tag name is "p"
*/
case '-P':
if ( ! $this->state->stack_of_open_elements->has_p_in_button_scope() ) {
$this->insert_html_element( $this->state->current_token );
}
$this->close_a_p_element();
return true;
// > A start tag whose tag name is "a"
case '+A':
foreach ( $this->state->active_formatting_elements->walk_up() as $item ) {
switch ( $item->node_name ) {
case 'marker':
break;
case 'A':
$this->run_adoption_agency_algorithm();
$this->state->active_formatting_elements->remove_node( $item );
$this->state->stack_of_open_elements->remove_node( $item );
break;
}
}
$this->reconstruct_active_formatting_elements();
$this->insert_html_element( $this->state->current_token );
$this->state->active_formatting_elements->push( $this->state->current_token );
return true;
/*
* > A start tag whose tag name is one of: "b", "big", "code", "em", "font", "i",
* > "s", "small", "strike", "strong", "tt", "u"
*/
case '+B':
case '+BIG':
case '+CODE':
case '+EM':
case '+FONT':
case '+I':
case '+S':
case '+SMALL':
case '+STRIKE':
case '+STRONG':
case '+TT':
case '+U':
$this->reconstruct_active_formatting_elements();
$this->insert_html_element( $this->state->current_token );
$this->state->active_formatting_elements->push( $this->state->current_token );
return true;
/*
* > An end tag whose tag name is one of: "a", "b", "big", "code", "em", "font", "i",
* > "nobr", "s", "small", "strike", "strong", "tt", "u"
*/
case '-A':
case '-B':
case '-BIG':
case '-CODE':
case '-EM':
case '-FONT':
case '-I':
case '-S':
case '-SMALL':
case '-STRIKE':
case '-STRONG':
case '-TT':
case '-U':
$this->run_adoption_agency_algorithm();
return true;
/*
* > A start tag whose tag name is one of: "area", "br", "embed", "img", "keygen", "wbr"
*/
case '+IMG':
$this->reconstruct_active_formatting_elements();
$this->insert_html_element( $this->state->current_token );
return true;
/*
* > Any other start tag
*/
case '+SPAN':
$this->reconstruct_active_formatting_elements();
$this->insert_html_element( $this->state->current_token );
return true;
/*
* Any other end tag
*/
case '-SPAN':
foreach ( $this->state->stack_of_open_elements->walk_up() as $item ) {
// > If node is an HTML element with the same tag name as the token, then:
if ( $item->node_name === $tag_name ) {
$this->generate_implied_end_tags( $tag_name );
// > If node is not the current node, then this is a parse error.
$this->state->stack_of_open_elements->pop_until( $tag_name );
return true;
}
// > Otherwise, if node is in the special category, then this is a parse error; ignore the token, and return.
if ( self::is_special( $item->node_name ) ) {
return $this->step();
}
}
// Execution should not reach here; if it does then something went wrong.
return false;
default:
$this->last_error = self::ERROR_UNSUPPORTED;
throw new WP_HTML_Unsupported_Exception( "Cannot process {$tag_name} element." );
}
}
/*
* Internal helpers
*/
/**
* Creates a new bookmark for the currently-matched tag and returns the generated name.
*
* @since 6.4.0
*
* @throws Exception When unable to allocate requested bookmark.
*
* @return string|false Name of created bookmark, or false if unable to create.
*/
private function bookmark_tag() {
if ( ! $this->get_tag() ) {
return false;
}
if ( ! parent::set_bookmark( ++$this->bookmark_counter ) ) {
$this->last_error = self::ERROR_EXCEEDED_MAX_BOOKMARKS;
throw new Exception( 'could not allocate bookmark' );
}
return "{$this->bookmark_counter}";
}
/*
* HTML semantic overrides for Tag Processor
*/
/**
* Returns the uppercase name of the matched tag.
*
* The semantic rules for HTML specify that certain tags be reprocessed
* with a different tag name. Because of this, the tag name presented
* by the HTML Processor may differ from the one reported by the HTML
* Tag Processor, which doesn't apply these semantic rules.
*
* Example:
*
* $processor = new WP_HTML_Tag_Processor( 'Test
' );
* $processor->next_tag() === true;
* $processor->get_tag() === 'DIV';
*
* $processor->next_tag() === false;
* $processor->get_tag() === null;
*
* @since 6.4.0
*
* @return string|null Name of currently matched tag in input HTML, or `null` if none found.
*/
public function get_tag() {
if ( null !== $this->last_error ) {
return null;
}
$tag_name = parent::get_tag();
switch ( $tag_name ) {
case 'IMAGE':
/*
* > A start tag whose tag name is "image"
* > Change the token's tag name to "img" and reprocess it. (Don't ask.)
*/
return 'IMG';
default:
return $tag_name;
}
}
/**
* Removes a bookmark that is no longer needed.
*
* Releasing a bookmark frees up the small
* performance overhead it requires.
*
* @since 6.4.0
*
* @param string $bookmark_name Name of the bookmark to remove.
* @return bool Whether the bookmark already existed before removal.
*/
public function release_bookmark( $bookmark_name ) {
return parent::release_bookmark( "_{$bookmark_name}" );
}
/**
* Moves the internal cursor in the HTML Processor to a given bookmark's location.
*
* In order to prevent accidental infinite loops, there's a
* maximum limit on the number of times seek() can be called.
*
* @throws Exception When unable to allocate a bookmark for the next token in the input HTML document.
*
* @since 6.4.0
*
* @param string $bookmark_name Jump to the place in the document identified by this bookmark name.
* @return bool Whether the internal cursor was successfully moved to the bookmark's location.
*/
public function seek( $bookmark_name ) {
$actual_bookmark_name = "_{$bookmark_name}";
$processor_started_at = $this->state->current_token
? $this->bookmarks[ $this->state->current_token->bookmark_name ]->start
: 0;
$bookmark_starts_at = $this->bookmarks[ $actual_bookmark_name ]->start;
$direction = $bookmark_starts_at > $processor_started_at ? 'forward' : 'backward';
switch ( $direction ) {
case 'forward':
// When moving forwards, re-parse the document until reaching the same location as the original bookmark.
while ( $this->step() ) {
if ( $bookmark_starts_at === $this->bookmarks[ $this->state->current_token->bookmark_name ]->start ) {
return true;
}
}
return false;
case 'backward':
/*
* When moving backwards, clear out all existing stack entries which appear after the destination
* bookmark. These could be stored for later retrieval, but doing so would require additional
* memory overhead and also demand that references and bookmarks are updated as the document
* changes. In time this could be a valuable optimization, but it's okay to give up that
* optimization in exchange for more CPU time to recompute the stack, to re-parse the
* document that may have already been parsed once.
*/
foreach ( $this->state->stack_of_open_elements->walk_up() as $item ) {
if ( $bookmark_starts_at >= $this->bookmarks[ $item->bookmark_name ]->start ) {
break;
}
$this->state->stack_of_open_elements->remove_node( $item );
}
foreach ( $this->state->active_formatting_elements->walk_up() as $item ) {
if ( $bookmark_starts_at >= $this->bookmarks[ $item->bookmark_name ]->start ) {
break;
}
$this->state->active_formatting_elements->remove_node( $item );
}
return parent::seek( $actual_bookmark_name );
}
}
/**
* Sets a bookmark in the HTML document.
*
* Bookmarks represent specific places or tokens in the HTML
* document, such as a tag opener or closer. When applying
* edits to a document, such as setting an attribute, the
* text offsets of that token may shift; the bookmark is
* kept updated with those shifts and remains stable unless
* the entire span of text in which the token sits is removed.
*
* Release bookmarks when they are no longer needed.
*
* Example:
*
* Surprising fact you may not know!
* ^ ^
* \-|-- this `H2` opener bookmark tracks the token
*
* Surprising fact you may no…
* ^ ^
* \-|-- it shifts with edits
*
* Bookmarks provide the ability to seek to a previously-scanned
* place in the HTML document. This avoids the need to re-scan
* the entire document.
*
* Example:
*
*
* ^^^^
* want to note this last item
*
* $p = new WP_HTML_Tag_Processor( $html );
* $in_list = false;
* while ( $p->next_tag( array( 'tag_closers' => $in_list ? 'visit' : 'skip' ) ) ) {
* if ( 'UL' === $p->get_tag() ) {
* if ( $p->is_tag_closer() ) {
* $in_list = false;
* $p->set_bookmark( 'resume' );
* if ( $p->seek( 'last-li' ) ) {
* $p->add_class( 'last-li' );
* }
* $p->seek( 'resume' );
* $p->release_bookmark( 'last-li' );
* $p->release_bookmark( 'resume' );
* } else {
* $in_list = true;
* }
* }
*
* if ( 'LI' === $p->get_tag() ) {
* $p->set_bookmark( 'last-li' );
* }
* }
*
* Bookmarks intentionally hide the internal string offsets
* to which they refer. They are maintained internally as
* updates are applied to the HTML document and therefore
* retain their "position" - the location to which they
* originally pointed. The inability to use bookmarks with
* functions like `substr` is therefore intentional to guard
* against accidentally breaking the HTML.
*
* Because bookmarks allocate memory and require processing
* for every applied update, they are limited and require
* a name. They should not be created with programmatically-made
* names, such as "li_{$index}" with some loop. As a general
* rule they should only be created with string-literal names
* like "start-of-section" or "last-paragraph".
*
* Bookmarks are a powerful tool to enable complicated behavior.
* Consider double-checking that you need this tool if you are
* reaching for it, as inappropriate use could lead to broken
* HTML structure or unwanted processing overhead.
*
* @since 6.4.0
*
* @param string $bookmark_name Identifies this particular bookmark.
* @return bool Whether the bookmark was successfully created.
*/
public function set_bookmark( $bookmark_name ) {
return parent::set_bookmark( "_{$bookmark_name}" );
}
/*
* HTML Parsing Algorithms
*/
/**
* Closes a P element.
*
* @since 6.4.0
*
* @throws WP_HTML_Unsupported_Exception When encountering unsupported HTML input.
*
* @see https://html.spec.whatwg.org/#close-a-p-element
*/
private function close_a_p_element() {
$this->generate_implied_end_tags( 'P' );
$this->state->stack_of_open_elements->pop_until( 'P' );
}
/**
* Closes elements that have implied end tags.
*
* @since 6.4.0
*
* @see https://html.spec.whatwg.org/#generate-implied-end-tags
*
* @param string|null $except_for_this_element Perform as if this element doesn't exist in the stack of open elements.
*/
private function generate_implied_end_tags( $except_for_this_element = null ) {
$elements_with_implied_end_tags = array(
'P',
);
$current_node = $this->state->stack_of_open_elements->current_node();
while (
$current_node && $current_node->node_name !== $except_for_this_element &&
in_array( $this->state->stack_of_open_elements->current_node(), $elements_with_implied_end_tags, true )
) {
$this->state->stack_of_open_elements->pop();
}
}
/**
* Closes elements that have implied end tags, thoroughly.
*
* See the HTML specification for an explanation why this is
* different from generating end tags in the normal sense.
*
* @since 6.4.0
*
* @see WP_HTML_Processor::generate_implied_end_tags
* @see https://html.spec.whatwg.org/#generate-implied-end-tags
*/
private function generate_implied_end_tags_thoroughly() {
$elements_with_implied_end_tags = array(
'P',
);
while ( in_array( $this->state->stack_of_open_elements->current_node(), $elements_with_implied_end_tags, true ) ) {
$this->state->stack_of_open_elements->pop();
}
}
/**
* Reconstructs the active formatting elements.
*
* > This has the effect of reopening all the formatting elements that were opened
* > in the current body, cell, or caption (whichever is youngest) that haven't
* > been explicitly closed.
*
* @since 6.4.0
*
* @throws WP_HTML_Unsupported_Exception When encountering unsupported HTML input.
*
* @see https://html.spec.whatwg.org/#reconstruct-the-active-formatting-elements
*
* @return bool Whether any formatting elements needed to be reconstructed.
*/
private function reconstruct_active_formatting_elements() {
/*
* > If there are no entries in the list of active formatting elements, then there is nothing
* > to reconstruct; stop this algorithm.
*/
if ( 0 === $this->state->active_formatting_elements->count() ) {
return false;
}
$last_entry = $this->state->active_formatting_elements->current_node();
if (
/*
* > If the last (most recently added) entry in the list of active formatting elements is a marker;
* > stop this algorithm.
*/
'marker' === $last_entry->node_name ||
/*
* > If the last (most recently added) entry in the list of active formatting elements is an
* > element that is in the stack of open elements, then there is nothing to reconstruct;
* > stop this algorithm.
*/
$this->state->stack_of_open_elements->contains_node( $last_entry )
) {
return false;
}
$this->last_error = self::ERROR_UNSUPPORTED;
throw new WP_HTML_Unsupported_Exception( 'Cannot reconstruct active formatting elements when advancing and rewinding is required.' );
}
/**
* Runs the adoption agency algorithm.
*
* @since 6.4.0
*
* @throws WP_HTML_Unsupported_Exception When encountering unsupported HTML input.
*
* @see https://html.spec.whatwg.org/#adoption-agency-algorithm
*/
private function run_adoption_agency_algorithm() {
$budget = 1000;
$subject = $this->get_tag();
$current_node = $this->state->stack_of_open_elements->current_node();
if (
// > If the current node is an HTML element whose tag name is subject
$current_node && $subject === $current_node->node_name &&
// > the current node is not in the list of active formatting elements
! $this->state->active_formatting_elements->contains_node( $current_node )
) {
$this->state->stack_of_open_elements->pop();
return;
}
$outer_loop_counter = 0;
while ( $budget-- > 0 ) {
if ( $outer_loop_counter++ >= 8 ) {
return;
}
/*
* > Let formatting element be the last element in the list of active formatting elements that:
* > - is between the end of the list and the last marker in the list,
* > if any, or the start of the list otherwise,
* > - and has the tag name subject.
*/
$formatting_element = null;
foreach ( $this->state->active_formatting_elements->walk_up() as $item ) {
if ( 'marker' === $item->node_name ) {
break;
}
if ( $subject === $item->node_name ) {
$formatting_element = $item;
break;
}
}
// > If there is no such element, then return and instead act as described in the "any other end tag" entry above.
if ( null === $formatting_element ) {
$this->last_error = self::ERROR_UNSUPPORTED;
throw new WP_HTML_Unsupported_Exception( 'Cannot run adoption agency when "any other end tag" is required.' );
}
// > If formatting element is not in the stack of open elements, then this is a parse error; remove the element from the list, and return.
if ( ! $this->state->stack_of_open_elements->contains_node( $formatting_element ) ) {
$this->state->active_formatting_elements->remove_node( $formatting_element->bookmark_name );
return;
}
// > If formatting element is in the stack of open elements, but the element is not in scope, then this is a parse error; return.
if ( ! $this->state->stack_of_open_elements->has_element_in_scope( $formatting_element->node_name ) ) {
return;
}
/*
* > Let furthest block be the topmost node in the stack of open elements that is lower in the stack
* > than formatting element, and is an element in the special category. There might not be one.
*/
$is_above_formatting_element = true;
$furthest_block = null;
foreach ( $this->state->stack_of_open_elements->walk_down() as $item ) {
if ( $is_above_formatting_element && $formatting_element->bookmark_name !== $item->bookmark_name ) {
continue;
}
if ( $is_above_formatting_element ) {
$is_above_formatting_element = false;
continue;
}
if ( self::is_special( $item->node_name ) ) {
$furthest_block = $item;
break;
}
}
/*
* > If there is no furthest block, then the UA must first pop all the nodes from the bottom of the
* > stack of open elements, from the current node up to and including formatting element, then
* > remove formatting element from the list of active formatting elements, and finally return.
*/
if ( null === $furthest_block ) {
foreach ( $this->state->stack_of_open_elements->walk_up() as $item ) {
$this->state->stack_of_open_elements->pop();
if ( $formatting_element->bookmark_name === $item->bookmark_name ) {
$this->state->active_formatting_elements->remove_node( $formatting_element );
return;
}
}
}
$this->last_error = self::ERROR_UNSUPPORTED;
throw new WP_HTML_Unsupported_Exception( 'Cannot extract common ancestor in adoption agency algorithm.' );
}
$this->last_error = self::ERROR_UNSUPPORTED;
throw new WP_HTML_Unsupported_Exception( 'Cannot run adoption agency when looping required.' );
}
/**
* Inserts an HTML element on the stack of open elements.
*
* @since 6.4.0
*
* @see https://html.spec.whatwg.org/#insert-a-foreign-element
*
* @param WP_HTML_Token $token Name of bookmark pointing to element in original input HTML.
*/
private function insert_html_element( $token ) {
$this->state->stack_of_open_elements->push( $token );
}
/*
* HTML Specification Helpers
*/
/**
* Returns whether an element of a given name is in the HTML special category.
*
* @since 6.4.0
*
* @see https://html.spec.whatwg.org/#special
*
* @param string $tag_name Name of element to check.
* @return bool Whether the element of the given name is in the special category.
*/
public static function is_special( $tag_name ) {
$tag_name = strtoupper( $tag_name );
return (
'ADDRESS' === $tag_name ||
'APPLET' === $tag_name ||
'AREA' === $tag_name ||
'ARTICLE' === $tag_name ||
'ASIDE' === $tag_name ||
'BASE' === $tag_name ||
'BASEFONT' === $tag_name ||
'BGSOUND' === $tag_name ||
'BLOCKQUOTE' === $tag_name ||
'BODY' === $tag_name ||
'BR' === $tag_name ||
'BUTTON' === $tag_name ||
'CAPTION' === $tag_name ||
'CENTER' === $tag_name ||
'COL' === $tag_name ||
'COLGROUP' === $tag_name ||
'DD' === $tag_name ||
'DETAILS' === $tag_name ||
'DIR' === $tag_name ||
'DIV' === $tag_name ||
'DL' === $tag_name ||
'DT' === $tag_name ||
'EMBED' === $tag_name ||
'FIELDSET' === $tag_name ||
'FIGCAPTION' === $tag_name ||
'FIGURE' === $tag_name ||
'FOOTER' === $tag_name ||
'FORM' === $tag_name ||
'FRAME' === $tag_name ||
'FRAMESET' === $tag_name ||
'H1' === $tag_name ||
'H2' === $tag_name ||
'H3' === $tag_name ||
'H4' === $tag_name ||
'H5' === $tag_name ||
'H6' === $tag_name ||
'HEAD' === $tag_name ||
'HEADER' === $tag_name ||
'HGROUP' === $tag_name ||
'HR' === $tag_name ||
'HTML' === $tag_name ||
'IFRAME' === $tag_name ||
'IMG' === $tag_name ||
'INPUT' === $tag_name ||
'KEYGEN' === $tag_name ||
'LI' === $tag_name ||
'LINK' === $tag_name ||
'LISTING' === $tag_name ||
'MAIN' === $tag_name ||
'MARQUEE' === $tag_name ||
'MENU' === $tag_name ||
'META' === $tag_name ||
'NAV' === $tag_name ||
'NOEMBED' === $tag_name ||
'NOFRAMES' === $tag_name ||
'NOSCRIPT' === $tag_name ||
'OBJECT' === $tag_name ||
'OL' === $tag_name ||
'P' === $tag_name ||
'PARAM' === $tag_name ||
'PLAINTEXT' === $tag_name ||
'PRE' === $tag_name ||
'SCRIPT' === $tag_name ||
'SEARCH' === $tag_name ||
'SECTION' === $tag_name ||
'SELECT' === $tag_name ||
'SOURCE' === $tag_name ||
'STYLE' === $tag_name ||
'SUMMARY' === $tag_name ||
'TABLE' === $tag_name ||
'TBODY' === $tag_name ||
'TD' === $tag_name ||
'TEMPLATE' === $tag_name ||
'TEXTAREA' === $tag_name ||
'TFOOT' === $tag_name ||
'TH' === $tag_name ||
'THEAD' === $tag_name ||
'TITLE' === $tag_name ||
'TR' === $tag_name ||
'TRACK' === $tag_name ||
'UL' === $tag_name ||
'WBR' === $tag_name ||
'XMP' === $tag_name ||
// MathML.
'MI' === $tag_name ||
'MO' === $tag_name ||
'MN' === $tag_name ||
'MS' === $tag_name ||
'MTEXT' === $tag_name ||
'ANNOTATION-XML' === $tag_name ||
// SVG.
'FOREIGNOBJECT' === $tag_name ||
'DESC' === $tag_name ||
'TITLE' === $tag_name
);
}
/**
* Returns whether a given element is an HTML Void Element
*
* > area, base, br, col, embed, hr, img, input, link, meta, source, track, wbr
*
* @since 6.4.0
*
* @see https://html.spec.whatwg.org/#void-elements
*
* @param string $tag_name Name of HTML tag to check.
* @return bool Whether the given tag is an HTML Void Element.
*/
public static function is_void( $tag_name ) {
$tag_name = strtoupper( $tag_name );
return (
'AREA' === $tag_name ||
'BASE' === $tag_name ||
'BR' === $tag_name ||
'COL' === $tag_name ||
'EMBED' === $tag_name ||
'HR' === $tag_name ||
'IMG' === $tag_name ||
'INPUT' === $tag_name ||
'LINK' === $tag_name ||
'META' === $tag_name ||
'SOURCE' === $tag_name ||
'TRACK' === $tag_name ||
'WBR' === $tag_name
);
}
/*
* Constants that would pollute the top of the class if they were found there.
*/
/**
* Indicates that the next HTML token should be parsed and processed.
*
* @since 6.4.0
*
* @var string
*/
const PROCESS_NEXT_NODE = 'process-next-node';
/**
* Indicates that the current HTML token should be reprocessed in the newly-selected insertion mode.
*
* @since 6.4.0
*
* @var string
*/
const REPROCESS_CURRENT_NODE = 'reprocess-current-node';
/**
* Indicates that the parser encountered unsupported markup and has bailed.
*
* @since 6.4.0
*
* @var string
*/
const ERROR_UNSUPPORTED = 'unsupported';
/**
* Indicates that the parser encountered more HTML tokens than it
* was able to process and has bailed.
*
* @since 6.4.0
*
* @var string
*/
const ERROR_EXCEEDED_MAX_BOOKMARKS = 'exceeded-max-bookmarks';
/**
* Unlock code that must be passed into the constructor to create this class.
*
* This class extends the WP_HTML_Tag_Processor, which has a public class
* constructor. Therefore, it's not possible to have a private constructor here.
*
* This unlock code is used to ensure that anyone calling the constructor is
* doing so with a full understanding that it's intended to be a private API.
*
* @access private
*/
const CONSTRUCTOR_UNLOCK_CODE = 'Use WP_HTML_Processor::create_fragment() instead of calling the class constructor directly.';
}
! isset( $defaults[ $name ] ) ) {
return null;
}
if ( empty( $defaults[ $name ]['type'] ) ) {
return $this->setSubGroup( $name );
}
return isset( $defaults[ $name ]['default'] )
? $defaults[ $name ]['default']
: null;
}
/**
* Gets the defaults options.
*
* @since 4.1.3
*
* @return array An array of dafults.
*/
public function getDefaults() {
return $this->defaults;
}
/**
* Updates the options in the database.
*
* @since 4.0.0
*
* @param string $optionsName An optional option name to update.
* @param string $defaults The defaults to filter the options by.
* @param array|null $options An optional options array.
* @return void
*/
public function update( $optionsName = null, $defaults = null, $options = null ) {
$optionsName = empty( $optionsName ) ? $this->optionsName : $optionsName;
$defaults = empty( $defaults ) ? $this->defaults : $defaults;
// First, we need to filter our options.
$options = $this->filterOptions( $defaults, $options );
// Refactor options.
$refactored = $this->convertOptionsToValues( $options );
$this->resetGroups();
// The following needs to happen here (possibly a clone) as well as in the main instance.
$originalInstance = $this->getOriginalInstance();
// Update the DB options.
aioseo()->core->optionsCache->setDb( $optionsName, $refactored );
// Force a save here and in the main class.
$this->shouldSave = true;
$originalInstance->shouldSave = true;
}
/**
* Updates the options in the database.
*
* @since 4.1.4
*
* @param boolean $force Whether or not to force an immediate save.
* @param string $optionsName An optional option name to update.
* @param string $defaults The defaults to filter the options by.
* @return void
*/
public function save( $force = false, $optionsName = null, $defaults = null ) {
if ( ! $this->shouldSave && ! $force ) {
return;
}
$optionsName = empty( $optionsName ) ? $this->optionsName : $optionsName;
$defaults = empty( $defaults ) ? $this->defaults : $defaults;
$this->update( $optionsName );
// First, we need to filter our options.
$options = $this->filterOptions( $defaults );
// Refactor options.
$refactored = $this->convertOptionsToValues( $options );
$this->resetGroups();
update_option( $optionsName, wp_json_encode( $refactored ) );
}
/**
* Filter options to match our defaults.
*
* @since 4.0.0
*
* @param array $defaults The defaults to use in filtering.
* @param array|null $options An optional options array.
* @return array An array of filtered options.
*/
public function filterOptions( $defaults, $options = null ) {
$cachedOptions = aioseo()->core->optionsCache->getOptions( $this->optionsName );
$options = ! empty( $options ) ? $options : json_decode( wp_json_encode( $cachedOptions ), true );
return $this->filterRecursively( $options, $defaults );
}
/**
* Filters options in a loop.
*
* @since 4.0.0
*
* @param array $options An array of options to filter.
* @param array $defaults An array of defaults to filter against.
* @return array A filtered array of options.
*/
public function filterRecursively( $options, $defaults ) {
if ( ! is_array( $options ) ) {
return $options;
}
foreach ( $options as $key => $value ) {
if ( ! isset( $defaults[ $key ] ) ) {
unset( $options[ $key ] );
continue;
}
if ( ! isset( $value['type'] ) ) {
$options[ $key ] = $this->filterRecursively( $options[ $key ], $defaults[ $key ] );
continue;
}
}
return $options;
}
/**
* Sanitizes the value before allowing it to be saved.
*
* @since 4.0.0
*
* @param mixed $value The value to sanitize.
* @param string $type The type of sanitization to do.
* @return mixed The sanitized value.
*/
public function sanitizeField( $value, $type, $preserveHtml = false ) {
switch ( $type ) {
case 'boolean':
return (bool) $value;
case 'html':
return sanitize_textarea_field( $value );
case 'string':
return sanitize_text_field( $value );
case 'number':
return intval( $value );
case 'array':
$array = [];
foreach ( (array) $value as $k => $v ) {
if ( is_array( $v ) ) {
$array[ $k ] = $this->sanitizeField( $v, 'array' );
continue;
}
$array[ $k ] = sanitize_text_field( $preserveHtml ? htmlspecialchars( $v, ENT_NOQUOTES, 'UTF-8' ) : $v );
}
return $array;
case 'float':
return floatval( $value );
}
}
/**
* Checks to see if we need to set the group key. If so, will return true.
*
* @since 4.0.0
*
* @param string $name The name of the option to set.
* @param array $arguments Any arguments needed if this was a method called.
* @param mixed $value The value if we are setting an option.
* @return boolean Whether or not we need to set the group key.
*/
private function setGroupKey( $name, $arguments = null, $value = null ) {
$this->arguments = $arguments;
$this->value = $value;
if ( empty( $this->groupKey ) ) {
$groups = array_keys( $this->defaultsMerged );
if ( in_array( $name, $groups, true ) ) {
$this->groupKey = $name;
return true;
}
$this->groupKey = $groups[0];
}
return false;
}
/**
* Sets the sub group key. Will set and return the instance.
*
* @since 4.0.0
*
* @param string $name The name of the option to set.
* @param array $arguments Any arguments needed if this was a method called.
* @param mixed $value The value if we are setting an option.
* @return object The options object.
*/
private function setSubGroup( $name, $arguments = null, $value = null ) {
if ( ! is_null( $arguments ) ) {
$this->arguments = $arguments;
}
if ( ! is_null( $value ) ) {
$this->value = $value;
}
$defaults = $this->defaultsMerged[ $this->groupKey ];
if ( ! empty( $this->subGroups ) ) {
foreach ( $this->subGroups as $subGroup ) {
$defaults = $defaults[ $subGroup ];
}
}
$groups = array_keys( $defaults );
if ( in_array( $name, $groups, true ) ) {
$this->subGroups[] = $name;
}
return $this;
}
/**
* Reset groups.
*
* @since 4.0.0
*
* @return void
*/
protected function resetGroups() {
$this->groupKey = null;
$this->subGroups = [];
}
/**
* Converts an associative array of values into a structure
* that works with our defaults.
*
* @since 4.0.0
*
* @param array $defaults The defaults array we are currently working with.
* @param array $values The values to adjust.
* @param array $keys Parent keys for the current group we are parsing.
* @param bool $sanitize Whether or not we should sanitize the value.
* @return array The modified values.
*/
protected function addValueToValuesArray( $defaults, $values, $keys = [], $sanitize = false ) {
foreach ( $values as $key => $value ) {
$option = $this->isAnOption( $key, $defaults, $keys );
if ( $option ) {
$preserveHtml = ! empty( $option['preserveHtml'] );
$newValue = $sanitize ? $this->sanitizeField( $value, $option['type'], $preserveHtml ) : $value;
$values[ $key ] = [
'value' => $newValue
];
// If this is a localized string, let's save it to our localized options.
if ( $sanitize && ! empty( $option['localized'] ) ) {
$localizedKey = '';
foreach ( $keys as $k ) {
$localizedKey .= $k . '_';
}
$localizedKey .= $key;
$localizedValue = $newValue;
if ( 'keywords' === $key ) {
$keywords = json_decode( $localizedValue ) ? json_decode( $localizedValue ) : [];
foreach ( $keywords as $k => $keyword ) {
$keywords[ $k ] = $keyword->value;
}
$localizedValue = implode( ',', $keywords );
}
$this->localized[ $localizedKey ] = $localizedValue;
}
continue;
}
if ( ! is_array( $value ) ) {
continue;
}
$keys[] = $key;
$values[ $key ] = $this->addValueToValuesArray( $defaults, $value, $keys, $sanitize );
array_pop( $keys );
}
return $values;
}
/**
* Our options array has values (or defaults).
* This method converts them to how we would store them
* in the DB.
*
* @since 4.0.0
*
* @param array $options The options array.
* @return array The converted options array.
*/
public function convertOptionsToValues( $options, $optionKey = 'type' ) {
foreach ( $options as $key => $value ) {
if ( ! is_array( $value ) ) {
continue;
}
if ( ! isset( $value[ $optionKey ] ) ) {
$options[ $key ] = $this->convertOptionsToValues( $value, $optionKey );
continue;
}
$options[ $key ] = null;
if ( isset( $value['value'] ) ) {
$preserveHtml = ! empty( $value['preserveHtml'] );
if ( $preserveHtml ) {
if ( is_array( $value['value'] ) ) {
foreach ( $value['value'] as $k => $v ) {
$value['value'][ $k ] = html_entity_decode( $v, ENT_NOQUOTES );
}
} else {
$value['value'] = html_entity_decode( $value['value'], ENT_NOQUOTES );
}
}
$options[ $key ] = $value['value'];
continue;
}
if ( isset( $value['default'] ) ) {
$options[ $key ] = $value['default'];
}
}
return $options;
}
/**
* This checks to see if the current array/option is really an option
* and not just another parent with a subgroup.
*
* @since 4.0.0
*
* @param string $key The current array key we are working with.
* @param array $defaults The defaults array to check against.
* @param array $keys The parent keys to loop through.
* @return bool Whether or not this is an option.
*/
private function isAnOption( $key, $defaults, $keys ) {
if ( ! empty( $keys ) ) {
foreach ( $keys as $k ) {
$defaults = isset( $defaults[ $k ] ) ? $defaults[ $k ] : [];
}
}
if ( isset( $defaults[ $key ]['type'] ) ) {
return $defaults[ $key ];
}
return false;
}
/**
* Refreshes the options from the database.
*
* We need this during the migration to update through clones.
*
* @since 4.0.0
*
* @return void
*/
public function refresh() {
// Reset DB options to clear the cache.
aioseo()->core->optionsCache->resetDb();
$this->init();
}
/**
* Returns the DB options.
*
* @since 4.1.4
*
* @param string $optionsName The options name.
* @return array The options.
*/
public function getDbOptions( $optionsName ) {
$cache = aioseo()->core->optionsCache->getDb( $optionsName );
if ( empty( $cache ) ) {
$options = json_decode( get_option( $optionsName ), true );
$options = ! empty( $options ) ? $options : [];
// Set the cache.
aioseo()->core->optionsCache->setDb( $optionsName, $options );
}
return aioseo()->core->optionsCache->getDb( $optionsName );
}
/**
* In order to not have a conflict, we need to return a clone.
*
* @since 4.0.0
*
* @param bool $reInitialize Whether to reinitialize on the clone.
* @return object The cloned Options object.
*/
public function noConflict( $reInitialize = false ) {
$class = clone $this;
$class->isClone = true;
if ( $reInitialize ) {
$class->init();
}
return $class;
}
/**
* Get original instance. Since this could be a cloned object, let's get the original instance.
*
* @since 4.1.4
*
* @return self
*/
public function getOriginalInstance() {
if ( ! $this->isClone ) {
return $this;
}
$class = new \ReflectionClass( get_called_class() );
$optionName = aioseo()->helpers->toCamelCase( $class->getShortName() );
if ( isset( aioseo()->{ $optionName } ) ) {
return aioseo()->{ $optionName };
}
return $this;
}
}