/**
* Plugin API: WP_Hook class
*
* @package WordPress
* @subpackage Plugin
* @since 4.7.0
*/
/**
* Core class used to implement action and filter hook functionality.
*
* @since 4.7.0
*
* @see Iterator
* @see ArrayAccess
*/
#[AllowDynamicProperties]
final class WP_Hook implements Iterator, ArrayAccess {
/**
* Hook callbacks.
*
* @since 4.7.0
* @var array
*/
public $callbacks = array();
/**
* Priorities list.
*
* @since 6.4.0
* @var array
*/
protected $priorities = array();
/**
* The priority keys of actively running iterations of a hook.
*
* @since 4.7.0
* @var array
*/
private $iterations = array();
/**
* The current priority of actively running iterations of a hook.
*
* @since 4.7.0
* @var array
*/
private $current_priority = array();
/**
* Number of levels this hook can be recursively called.
*
* @since 4.7.0
* @var int
*/
private $nesting_level = 0;
/**
* Flag for if we're currently doing an action, rather than a filter.
*
* @since 4.7.0
* @var bool
*/
private $doing_action = false;
/**
* Adds a callback function to a filter hook.
*
* @since 4.7.0
*
* @param string $hook_name The name of the filter to add the callback to.
* @param callable $callback The callback to be run when the filter is applied.
* @param int $priority The order in which the functions associated with a particular filter
* are executed. Lower numbers correspond with earlier execution,
* and functions with the same priority are executed in the order
* in which they were added to the filter.
* @param int $accepted_args The number of arguments the function accepts.
*/
public function add_filter( $hook_name, $callback, $priority, $accepted_args ) {
$idx = _wp_filter_build_unique_id( $hook_name, $callback, $priority );
$priority_existed = isset( $this->callbacks[ $priority ] );
$this->callbacks[ $priority ][ $idx ] = array(
'function' => $callback,
'accepted_args' => (int) $accepted_args,
);
// If we're adding a new priority to the list, put them back in sorted order.
if ( ! $priority_existed && count( $this->callbacks ) > 1 ) {
ksort( $this->callbacks, SORT_NUMERIC );
}
$this->priorities = array_keys( $this->callbacks );
if ( $this->nesting_level > 0 ) {
$this->resort_active_iterations( $priority, $priority_existed );
}
}
/**
* Handles resetting callback priority keys mid-iteration.
*
* @since 4.7.0
*
* @param false|int $new_priority Optional. The priority of the new filter being added. Default false,
* for no priority being added.
* @param bool $priority_existed Optional. Flag for whether the priority already existed before the new
* filter was added. Default false.
*/
private function resort_active_iterations( $new_priority = false, $priority_existed = false ) {
$new_priorities = $this->priorities;
// If there are no remaining hooks, clear out all running iterations.
if ( ! $new_priorities ) {
foreach ( $this->iterations as $index => $iteration ) {
$this->iterations[ $index ] = $new_priorities;
}
return;
}
$min = min( $new_priorities );
foreach ( $this->iterations as $index => &$iteration ) {
$current = current( $iteration );
// If we're already at the end of this iteration, just leave the array pointer where it is.
if ( false === $current ) {
continue;
}
$iteration = $new_priorities;
if ( $current < $min ) {
array_unshift( $iteration, $current );
continue;
}
while ( current( $iteration ) < $current ) {
if ( false === next( $iteration ) ) {
break;
}
}
// If we have a new priority that didn't exist, but ::apply_filters() or ::do_action() thinks it's the current priority...
if ( $new_priority === $this->current_priority[ $index ] && ! $priority_existed ) {
/*
* ...and the new priority is the same as what $this->iterations thinks is the previous
* priority, we need to move back to it.
*/
if ( false === current( $iteration ) ) {
// If we've already moved off the end of the array, go back to the last element.
$prev = end( $iteration );
} else {
// Otherwise, just go back to the previous element.
$prev = prev( $iteration );
}
if ( false === $prev ) {
// Start of the array. Reset, and go about our day.
reset( $iteration );
} elseif ( $new_priority !== $prev ) {
// Previous wasn't the same. Move forward again.
next( $iteration );
}
}
}
unset( $iteration );
}
/**
* Removes a callback function from a filter hook.
*
* @since 4.7.0
*
* @param string $hook_name The filter hook to which the function to be removed is hooked.
* @param callable|string|array $callback The callback to be removed from running when the filter is applied.
* This method can be called unconditionally to speculatively remove
* a callback that may or may not exist.
* @param int $priority The exact priority used when adding the original filter callback.
* @return bool Whether the callback existed before it was removed.
*/
public function remove_filter( $hook_name, $callback, $priority ) {
$function_key = _wp_filter_build_unique_id( $hook_name, $callback, $priority );
$exists = isset( $this->callbacks[ $priority ][ $function_key ] );
if ( $exists ) {
unset( $this->callbacks[ $priority ][ $function_key ] );
if ( ! $this->callbacks[ $priority ] ) {
unset( $this->callbacks[ $priority ] );
$this->priorities = array_keys( $this->callbacks );
if ( $this->nesting_level > 0 ) {
$this->resort_active_iterations();
}
}
}
return $exists;
}
/**
* Checks if a specific callback has been registered for this hook.
*
* When using the `$callback` argument, this function may return a non-boolean value
* that evaluates to false (e.g. 0), so use the `===` operator for testing the return value.
*
* @since 4.7.0
*
* @param string $hook_name Optional. The name of the filter hook. Default empty.
* @param callable|string|array|false $callback Optional. The callback to check for.
* This method can be called unconditionally to speculatively check
* a callback that may or may not exist. Default false.
* @return bool|int If `$callback` is omitted, returns boolean for whether the hook has
* anything registered. When checking a specific function, the priority
* of that hook is returned, or false if the function is not attached.
*/
public function has_filter( $hook_name = '', $callback = false ) {
if ( false === $callback ) {
return $this->has_filters();
}
$function_key = _wp_filter_build_unique_id( $hook_name, $callback, false );
if ( ! $function_key ) {
return false;
}
foreach ( $this->callbacks as $priority => $callbacks ) {
if ( isset( $callbacks[ $function_key ] ) ) {
return $priority;
}
}
return false;
}
/**
* Checks if any callbacks have been registered for this hook.
*
* @since 4.7.0
*
* @return bool True if callbacks have been registered for the current hook, otherwise false.
*/
public function has_filters() {
foreach ( $this->callbacks as $callbacks ) {
if ( $callbacks ) {
return true;
}
}
return false;
}
/**
* Removes all callbacks from the current filter.
*
* @since 4.7.0
*
* @param int|false $priority Optional. The priority number to remove. Default false.
*/
public function remove_all_filters( $priority = false ) {
if ( ! $this->callbacks ) {
return;
}
if ( false === $priority ) {
$this->callbacks = array();
$this->priorities = array();
} elseif ( isset( $this->callbacks[ $priority ] ) ) {
unset( $this->callbacks[ $priority ] );
$this->priorities = array_keys( $this->callbacks );
}
if ( $this->nesting_level > 0 ) {
$this->resort_active_iterations();
}
}
/**
* Calls the callback functions that have been added to a filter hook.
*
* @since 4.7.0
*
* @param mixed $value The value to filter.
* @param array $args Additional parameters to pass to the callback functions.
* This array is expected to include $value at index 0.
* @return mixed The filtered value after all hooked functions are applied to it.
*/
public function apply_filters( $value, $args ) {
if ( ! $this->callbacks ) {
return $value;
}
$nesting_level = $this->nesting_level++;
$this->iterations[ $nesting_level ] = $this->priorities;
$num_args = count( $args );
do {
$this->current_priority[ $nesting_level ] = current( $this->iterations[ $nesting_level ] );
$priority = $this->current_priority[ $nesting_level ];
foreach ( $this->callbacks[ $priority ] as $the_ ) {
if ( ! $this->doing_action ) {
$args[0] = $value;
}
// Avoid the array_slice() if possible.
if ( 0 === $the_['accepted_args'] ) {
$value = call_user_func( $the_['function'] );
} elseif ( $the_['accepted_args'] >= $num_args ) {
$value = call_user_func_array( $the_['function'], $args );
} else {
$value = call_user_func_array( $the_['function'], array_slice( $args, 0, $the_['accepted_args'] ) );
}
}
} while ( false !== next( $this->iterations[ $nesting_level ] ) );
unset( $this->iterations[ $nesting_level ] );
unset( $this->current_priority[ $nesting_level ] );
--$this->nesting_level;
return $value;
}
/**
* Calls the callback functions that have been added to an action hook.
*
* @since 4.7.0
*
* @param array $args Parameters to pass to the callback functions.
*/
public function do_action( $args ) {
$this->doing_action = true;
$this->apply_filters( '', $args );
// If there are recursive calls to the current action, we haven't finished it until we get to the last one.
if ( ! $this->nesting_level ) {
$this->doing_action = false;
}
}
/**
* Processes the functions hooked into the 'all' hook.
*
* @since 4.7.0
*
* @param array $args Arguments to pass to the hook callbacks. Passed by reference.
*/
public function do_all_hook( &$args ) {
$nesting_level = $this->nesting_level++;
$this->iterations[ $nesting_level ] = $this->priorities;
do {
$priority = current( $this->iterations[ $nesting_level ] );
foreach ( $this->callbacks[ $priority ] as $the_ ) {
call_user_func_array( $the_['function'], $args );
}
} while ( false !== next( $this->iterations[ $nesting_level ] ) );
unset( $this->iterations[ $nesting_level ] );
--$this->nesting_level;
}
/**
* Return the current priority level of the currently running iteration of the hook.
*
* @since 4.7.0
*
* @return int|false If the hook is running, return the current priority level.
* If it isn't running, return false.
*/
public function current_priority() {
if ( false === current( $this->iterations ) ) {
return false;
}
return current( current( $this->iterations ) );
}
/**
* Normalizes filters set up before WordPress has initialized to WP_Hook objects.
*
* The `$filters` parameter should be an array keyed by hook name, with values
* containing either:
*
* - A `WP_Hook` instance
* - An array of callbacks keyed by their priorities
*
* Examples:
*
* $filters = array(
* 'wp_fatal_error_handler_enabled' => array(
* 10 => array(
* array(
* 'accepted_args' => 0,
* 'function' => function() {
* return false;
* },
* ),
* ),
* ),
* );
*
* @since 4.7.0
*
* @param array $filters Filters to normalize. See documentation above for details.
* @return WP_Hook[] Array of normalized filters.
*/
public static function build_preinitialized_hooks( $filters ) {
/** @var WP_Hook[] $normalized */
$normalized = array();
foreach ( $filters as $hook_name => $callback_groups ) {
if ( $callback_groups instanceof WP_Hook ) {
$normalized[ $hook_name ] = $callback_groups;
continue;
}
$hook = new WP_Hook();
// Loop through callback groups.
foreach ( $callback_groups as $priority => $callbacks ) {
// Loop through callbacks.
foreach ( $callbacks as $cb ) {
$hook->add_filter( $hook_name, $cb['function'], $priority, $cb['accepted_args'] );
}
}
$normalized[ $hook_name ] = $hook;
}
return $normalized;
}
/**
* Determines whether an offset value exists.
*
* @since 4.7.0
*
* @link https://www.php.net/manual/en/arrayaccess.offsetexists.php
*
* @param mixed $offset An offset to check for.
* @return bool True if the offset exists, false otherwise.
*/
#[ReturnTypeWillChange]
public function offsetExists( $offset ) {
return isset( $this->callbacks[ $offset ] );
}
/**
* Retrieves a value at a specified offset.
*
* @since 4.7.0
*
* @link https://www.php.net/manual/en/arrayaccess.offsetget.php
*
* @param mixed $offset The offset to retrieve.
* @return mixed If set, the value at the specified offset, null otherwise.
*/
#[ReturnTypeWillChange]
public function offsetGet( $offset ) {
return isset( $this->callbacks[ $offset ] ) ? $this->callbacks[ $offset ] : null;
}
/**
* Sets a value at a specified offset.
*
* @since 4.7.0
*
* @link https://www.php.net/manual/en/arrayaccess.offsetset.php
*
* @param mixed $offset The offset to assign the value to.
* @param mixed $value The value to set.
*/
#[ReturnTypeWillChange]
public function offsetSet( $offset, $value ) {
if ( is_null( $offset ) ) {
$this->callbacks[] = $value;
} else {
$this->callbacks[ $offset ] = $value;
}
$this->priorities = array_keys( $this->callbacks );
}
/**
* Unsets a specified offset.
*
* @since 4.7.0
*
* @link https://www.php.net/manual/en/arrayaccess.offsetunset.php
*
* @param mixed $offset The offset to unset.
*/
#[ReturnTypeWillChange]
public function offsetUnset( $offset ) {
unset( $this->callbacks[ $offset ] );
$this->priorities = array_keys( $this->callbacks );
}
/**
* Returns the current element.
*
* @since 4.7.0
*
* @link https://www.php.net/manual/en/iterator.current.php
*
* @return array Of callbacks at current priority.
*/
#[ReturnTypeWillChange]
public function current() {
return current( $this->callbacks );
}
/**
* Moves forward to the next element.
*
* @since 4.7.0
*
* @link https://www.php.net/manual/en/iterator.next.php
*
* @return array Of callbacks at next priority.
*/
#[ReturnTypeWillChange]
public function next() {
return next( $this->callbacks );
}
/**
* Returns the key of the current element.
*
* @since 4.7.0
*
* @link https://www.php.net/manual/en/iterator.key.php
*
* @return mixed Returns current priority on success, or NULL on failure
*/
#[ReturnTypeWillChange]
public function key() {
return key( $this->callbacks );
}
/**
* Checks if current position is valid.
*
* @since 4.7.0
*
* @link https://www.php.net/manual/en/iterator.valid.php
*
* @return bool Whether the current position is valid.
*/
#[ReturnTypeWillChange]
public function valid() {
return key( $this->callbacks ) !== null;
}
/**
* Rewinds the Iterator to the first element.
*
* @since 4.7.0
*
* @link https://www.php.net/manual/en/iterator.rewind.php
*/
#[ReturnTypeWillChange]
public function rewind() {
reset( $this->callbacks );
}
}
/**
* Main WordPress Formatting API.
*
* Handles many functions for formatting output.
*
* @package WordPress
*/
/**
* Replaces common plain text characters with formatted entities.
*
* Returns given text with transformations of quotes into smart quotes, apostrophes,
* dashes, ellipses, the trademark symbol, and the multiplication symbol.
*
* As an example,
*
* 'cause today's effort makes it worth tomorrow's "holiday" ...
*
* Becomes:
*
* ’cause today’s effort makes it worth tomorrow’s “holiday” …
*
* Code within certain HTML blocks are skipped.
*
* Do not use this function before the {@see 'init'} action hook; everything will break.
*
* @since 0.71
*
* @global array $wp_cockneyreplace Array of formatted entities for certain common phrases.
* @global array $shortcode_tags
*
* @param string $text The text to be formatted.
* @param bool $reset Set to true for unit testing. Translated patterns will reset.
* @return string The string replaced with HTML entities.
*/
function wptexturize( $text, $reset = false ) {
global $wp_cockneyreplace, $shortcode_tags;
static $static_characters = null,
$static_replacements = null,
$dynamic_characters = null,
$dynamic_replacements = null,
$default_no_texturize_tags = null,
$default_no_texturize_shortcodes = null,
$run_texturize = true,
$apos = null,
$prime = null,
$double_prime = null,
$opening_quote = null,
$closing_quote = null,
$opening_single_quote = null,
$closing_single_quote = null,
$open_q_flag = '',
$open_sq_flag = '',
$apos_flag = '';
// If there's nothing to do, just stop.
if ( empty( $text ) || false === $run_texturize ) {
return $text;
}
// Set up static variables. Run once only.
if ( $reset || ! isset( $static_characters ) ) {
/**
* Filters whether to skip running wptexturize().
*
* Returning false from the filter will effectively short-circuit wptexturize()
* and return the original text passed to the function instead.
*
* The filter runs only once, the first time wptexturize() is called.
*
* @since 4.0.0
*
* @see wptexturize()
*
* @param bool $run_texturize Whether to short-circuit wptexturize().
*/
$run_texturize = apply_filters( 'run_wptexturize', $run_texturize );
if ( false === $run_texturize ) {
return $text;
}
/* translators: Opening curly double quote. */
$opening_quote = _x( '“', 'opening curly double quote' );
/* translators: Closing curly double quote. */
$closing_quote = _x( '”', 'closing curly double quote' );
/* translators: Apostrophe, for example in 'cause or can't. */
$apos = _x( '’', 'apostrophe' );
/* translators: Prime, for example in 9' (nine feet). */
$prime = _x( '′', 'prime' );
/* translators: Double prime, for example in 9" (nine inches). */
$double_prime = _x( '″', 'double prime' );
/* translators: Opening curly single quote. */
$opening_single_quote = _x( '‘', 'opening curly single quote' );
/* translators: Closing curly single quote. */
$closing_single_quote = _x( '’', 'closing curly single quote' );
/* translators: En dash. */
$en_dash = _x( '–', 'en dash' );
/* translators: Em dash. */
$em_dash = _x( '—', 'em dash' );
$default_no_texturize_tags = array( 'pre', 'code', 'kbd', 'style', 'script', 'tt' );
$default_no_texturize_shortcodes = array( 'code' );
// If a plugin has provided an autocorrect array, use it.
if ( isset( $wp_cockneyreplace ) ) {
$cockney = array_keys( $wp_cockneyreplace );
$cockneyreplace = array_values( $wp_cockneyreplace );
} else {
/*
* translators: This is a comma-separated list of words that defy the syntax of quotations in normal use,
* for example... 'We do not have enough words yet'... is a typical quoted phrase. But when we write
* lines of code 'til we have enough of 'em, then we need to insert apostrophes instead of quotes.
*/
$cockney = explode(
',',
_x(
"'tain't,'twere,'twas,'tis,'twill,'til,'bout,'nuff,'round,'cause,'em",
'Comma-separated list of words to texturize in your language'
)
);
$cockneyreplace = explode(
',',
_x(
'’tain’t,’twere,’twas,’tis,’twill,’til,’bout,’nuff,’round,’cause,’em',
'Comma-separated list of replacement words in your language'
)
);
}
$static_characters = array_merge( array( '...', '``', '\'\'', ' (tm)' ), $cockney );
$static_replacements = array_merge( array( '…', $opening_quote, $closing_quote, ' ™' ), $cockneyreplace );
/*
* Pattern-based replacements of characters.
* Sort the remaining patterns into several arrays for performance tuning.
*/
$dynamic_characters = array(
'apos' => array(),
'quote' => array(),
'dash' => array(),
);
$dynamic_replacements = array(
'apos' => array(),
'quote' => array(),
'dash' => array(),
);
$dynamic = array();
$spaces = wp_spaces_regexp();
// '99' and '99" are ambiguous among other patterns; assume it's an abbreviated year at the end of a quotation.
if ( "'" !== $apos || "'" !== $closing_single_quote ) {
$dynamic[ '/\'(\d\d)\'(?=\Z|[.,:;!?)}\-\]]|>|' . $spaces . ')/' ] = $apos_flag . '$1' . $closing_single_quote;
}
if ( "'" !== $apos || '"' !== $closing_quote ) {
$dynamic[ '/\'(\d\d)"(?=\Z|[.,:;!?)}\-\]]|>|' . $spaces . ')/' ] = $apos_flag . '$1' . $closing_quote;
}
// '99 '99s '99's (apostrophe) But never '9 or '99% or '999 or '99.0.
if ( "'" !== $apos ) {
$dynamic['/\'(?=\d\d(?:\Z|(?![%\d]|[.,]\d)))/'] = $apos_flag;
}
// Quoted numbers like '0.42'.
if ( "'" !== $opening_single_quote && "'" !== $closing_single_quote ) {
$dynamic[ '/(?<=\A|' . $spaces . ')\'(\d[.,\d]*)\'/' ] = $open_sq_flag . '$1' . $closing_single_quote;
}
// Single quote at start, or preceded by (, {, <, [, ", -, or spaces.
if ( "'" !== $opening_single_quote ) {
$dynamic[ '/(?<=\A|[([{"\-]|<|' . $spaces . ')\'/' ] = $open_sq_flag;
}
// Apostrophe in a word. No spaces, double apostrophes, or other punctuation.
if ( "'" !== $apos ) {
$dynamic[ '/(?&/\[\]\x00-\x20=]++)@', $text, $matches );
$tagnames = array_intersect( array_keys( $shortcode_tags ), $matches[1] );
$found_shortcodes = ! empty( $tagnames );
$shortcode_regex = $found_shortcodes ? _get_wptexturize_shortcode_regex( $tagnames ) : '';
$regex = _get_wptexturize_split_regex( $shortcode_regex );
$textarr = preg_split( $regex, $text, -1, PREG_SPLIT_DELIM_CAPTURE | PREG_SPLIT_NO_EMPTY );
foreach ( $textarr as &$curl ) {
// Only call _wptexturize_pushpop_element if $curl is a delimiter.
$first = $curl[0];
if ( '<' === $first ) {
if ( str_starts_with( $curl, '';
$quote_pattern = "/$needle(?=\\Z|[.,:;!?)}\\-\\]]|>|" . $spaces . ')/';
$prime_pattern = "/(?<=\\d)$needle/";
$flag_after_digit = "/(?<=\\d)$flag/";
$flag_no_digit = "/(? &$sentence ) {
if ( ! str_contains( $sentence, $needle ) ) {
continue;
} elseif ( 0 !== $key && 0 === substr_count( $sentence, $close_quote ) ) {
$sentence = preg_replace( $quote_pattern, $flag, $sentence, -1, $count );
if ( $count > 1 ) {
// This sentence appears to have multiple closing quotes. Attempt Vulcan logic.
$sentence = preg_replace( $flag_no_digit, $close_quote, $sentence, -1, $count2 );
if ( 0 === $count2 ) {
// Try looking for a quote followed by a period.
$count2 = substr_count( $sentence, "$flag." );
if ( $count2 > 0 ) {
// Assume the rightmost quote-period match is the end of quotation.
$pos = strrpos( $sentence, "$flag." );
} else {
/*
* When all else fails, make the rightmost candidate a closing quote.
* This is most likely to be problematic in the context of bug #18549.
*/
$pos = strrpos( $sentence, $flag );
}
$sentence = substr_replace( $sentence, $close_quote, $pos, strlen( $flag ) );
}
// Use conventional replacement on any remaining primes and quotes.
$sentence = preg_replace( $prime_pattern, $prime, $sentence );
$sentence = preg_replace( $flag_after_digit, $prime, $sentence );
$sentence = str_replace( $flag, $close_quote, $sentence );
} elseif ( 1 === $count ) {
// Found only one closing quote candidate, so give it priority over primes.
$sentence = str_replace( $flag, $close_quote, $sentence );
$sentence = preg_replace( $prime_pattern, $prime, $sentence );
} else {
// No closing quotes found. Just run primes pattern.
$sentence = preg_replace( $prime_pattern, $prime, $sentence );
}
} else {
$sentence = preg_replace( $prime_pattern, $prime, $sentence );
$sentence = preg_replace( $quote_pattern, $close_quote, $sentence );
}
if ( '"' === $needle && str_contains( $sentence, '"' ) ) {
$sentence = str_replace( '"', $close_quote, $sentence );
}
}
return implode( $open_quote, $sentences );
}
/**
* Searches for disabled element tags. Pushes element to stack on tag open
* and pops on tag close.
*
* Assumes first char of `$text` is tag opening and last char is tag closing.
* Assumes second char of `$text` is optionally `/` to indicate closing as in `