1. <?php
  2. /**
  3. * Plugin API: WP_Hook class
  4. *
  5. * @package WordPress
  6. * @subpackage Plugin
  7. * @since 4.7.0
  8. */
  10. /**
  11. * Core class used to implement action and filter hook functionality.
  12. *
  13. * @since 4.7.0
  14. *
  15. * @see Iterator
  16. * @see ArrayAccess
  17. */
  18. #[AllowDynamicProperties]
  19. final class WP_Hook implements Iterator, ArrayAccess {
  21. /**
  22. * Hook callbacks.
  23. *
  24. * @since 4.7.0
  25. * @var array
  26. */
  27. public $callbacks = array();
  29. /**
  30. * Priorities list.
  31. *
  32. * @since 6.4.0
  33. * @var array
  34. */
  35. protected $priorities = array();
  37. /**
  38. * The priority keys of actively running iterations of a hook.
  39. *
  40. * @since 4.7.0
  41. * @var array
  42. */
  43. private $iterations = array();
  45. /**
  46. * The current priority of actively running iterations of a hook.
  47. *
  48. * @since 4.7.0
  49. * @var array
  50. */
  51. private $current_priority = array();
  53. /**
  54. * Number of levels this hook can be recursively called.
  55. *
  56. * @since 4.7.0
  57. * @var int
  58. */
  59. private $nesting_level = 0;
  61. /**
  62. * Flag for if we're currently doing an action, rather than a filter.
  63. *
  64. * @since 4.7.0
  65. * @var bool
  66. */
  67. private $doing_action = false;
  69. /**
  70. * Adds a callback function to a filter hook.
  71. *
  72. * @since 4.7.0
  73. *
  74. * @param string $hook_name The name of the filter to add the callback to.
  75. * @param callable $callback The callback to be run when the filter is applied.
  76. * @param int $priority The order in which the functions associated with a particular filter
  77. * are executed. Lower numbers correspond with earlier execution,
  78. * and functions with the same priority are executed in the order
  79. * in which they were added to the filter.
  80. * @param int $accepted_args The number of arguments the function accepts.
  81. */
  82. public function add_filter( $hook_name, $callback, $priority, $accepted_args ) {
  83. $idx = _wp_filter_build_unique_id( $hook_name, $callback, $priority );
  85. $priority_existed = isset( $this->callbacks[ $priority ] );
  87. $this->callbacks[ $priority ][ $idx ] = array(
  88. 'function' => $callback,
  89. 'accepted_args' => (int) $accepted_args,
  90. );
  92. // If we're adding a new priority to the list, put them back in sorted order.
  93. if ( ! $priority_existed && count( $this->callbacks ) > 1 ) {
  94. ksort( $this->callbacks, SORT_NUMERIC );
  95. }
  97. $this->priorities = array_keys( $this->callbacks );
  99. if ( $this->nesting_level > 0 ) {
  100. $this->resort_active_iterations( $priority, $priority_existed );
  101. }
  102. }
  104. /**
  105. * Handles resetting callback priority keys mid-iteration.
  106. *
  107. * @since 4.7.0
  108. *
  109. * @param false|int $new_priority Optional. The priority of the new filter being added. Default false,
  110. * for no priority being added.
  111. * @param bool $priority_existed Optional. Flag for whether the priority already existed before the new
  112. * filter was added. Default false.
  113. */
  114. private function resort_active_iterations( $new_priority = false, $priority_existed = false ) {
  115. $new_priorities = $this->priorities;
  117. // If there are no remaining hooks, clear out all running iterations.
  118. if ( ! $new_priorities ) {
  119. foreach ( $this->iterations as $index => $iteration ) {
  120. $this->iterations[ $index ] = $new_priorities;
  121. }
  123. return;
  124. }
  126. $min = min( $new_priorities );
  128. foreach ( $this->iterations as $index => &$iteration ) {
  129. $current = current( $iteration );
  131. // If we're already at the end of this iteration, just leave the array pointer where it is.
  132. if ( false === $current ) {
  133. continue;
  134. }
  136. $iteration = $new_priorities;
  138. if ( $current < $min ) {
  139. array_unshift( $iteration, $current );
  140. continue;
  141. }
  143. while ( current( $iteration ) < $current ) {
  144. if ( false === next( $iteration ) ) {
  145. break;
  146. }
  147. }
  149. // If we have a new priority that didn't exist, but ::apply_filters() or ::do_action() thinks it's the current priority...
  150. if ( $new_priority === $this->current_priority[ $index ] && ! $priority_existed ) {
  151. /*
  152. * ...and the new priority is the same as what $this->iterations thinks is the previous
  153. * priority, we need to move back to it.
  154. */
  156. if ( false === current( $iteration ) ) {
  157. // If we've already moved off the end of the array, go back to the last element.
  158. $prev = end( $iteration );
  159. } else {
  160. // Otherwise, just go back to the previous element.
  161. $prev = prev( $iteration );
  162. }
  164. if ( false === $prev ) {
  165. // Start of the array. Reset, and go about our day.
  166. reset( $iteration );
  167. } elseif ( $new_priority !== $prev ) {
  168. // Previous wasn't the same. Move forward again.
  169. next( $iteration );
  170. }
  171. }
  172. }
  174. unset( $iteration );
  175. }
  177. /**
  178. * Removes a callback function from a filter hook.
  179. *
  180. * @since 4.7.0
  181. *
  182. * @param string $hook_name The filter hook to which the function to be removed is hooked.
  183. * @param callable|string|array $callback The callback to be removed from running when the filter is applied.
  184. * This method can be called unconditionally to speculatively remove
  185. * a callback that may or may not exist.
  186. * @param int $priority The exact priority used when adding the original filter callback.
  187. * @return bool Whether the callback existed before it was removed.
  188. */
  189. public function remove_filter( $hook_name, $callback, $priority ) {
  190. $function_key = _wp_filter_build_unique_id( $hook_name, $callback, $priority );
  192. $exists = isset( $this->callbacks[ $priority ][ $function_key ] );
  194. if ( $exists ) {
  195. unset( $this->callbacks[ $priority ][ $function_key ] );
  197. if ( ! $this->callbacks[ $priority ] ) {
  198. unset( $this->callbacks[ $priority ] );
  200. $this->priorities = array_keys( $this->callbacks );
  202. if ( $this->nesting_level > 0 ) {
  203. $this->resort_active_iterations();
  204. }
  205. }
  206. }
  208. return $exists;
  209. }
  211. /**
  212. * Checks if a specific callback has been registered for this hook.
  213. *
  214. * When using the `$callback` argument, this function may return a non-boolean value
  215. * that evaluates to false (e.g. 0), so use the `===` operator for testing the return value.
  216. *
  217. * @since 4.7.0
  218. *
  219. * @param string $hook_name Optional. The name of the filter hook. Default empty.
  220. * @param callable|string|array|false $callback Optional. The callback to check for.
  221. * This method can be called unconditionally to speculatively check
  222. * a callback that may or may not exist. Default false.
  223. * @return bool|int If `$callback` is omitted, returns boolean for whether the hook has
  224. * anything registered. When checking a specific function, the priority
  225. * of that hook is returned, or false if the function is not attached.
  226. */
  227. public function has_filter( $hook_name = '', $callback = false ) {
  228. if ( false === $callback ) {
  229. return $this->has_filters();
  230. }
  232. $function_key = _wp_filter_build_unique_id( $hook_name, $callback, false );
  234. if ( ! $function_key ) {
  235. return false;
  236. }
  238. foreach ( $this->callbacks as $priority => $callbacks ) {
  239. if ( isset( $callbacks[ $function_key ] ) ) {
  240. return $priority;
  241. }
  242. }
  244. return false;
  245. }
  247. /**
  248. * Checks if any callbacks have been registered for this hook.
  249. *
  250. * @since 4.7.0
  251. *
  252. * @return bool True if callbacks have been registered for the current hook, otherwise false.
  253. */
  254. public function has_filters() {
  255. foreach ( $this->callbacks as $callbacks ) {
  256. if ( $callbacks ) {
  257. return true;
  258. }
  259. }
  261. return false;
  262. }
  264. /**
  265. * Removes all callbacks from the current filter.
  266. *
  267. * @since 4.7.0
  268. *
  269. * @param int|false $priority Optional. The priority number to remove. Default false.
  270. */
  271. public function remove_all_filters( $priority = false ) {
  272. if ( ! $this->callbacks ) {
  273. return;
  274. }
  276. if ( false === $priority ) {
  277. $this->callbacks = array();
  278. $this->priorities = array();
  279. } elseif ( isset( $this->callbacks[ $priority ] ) ) {
  280. unset( $this->callbacks[ $priority ] );
  281. $this->priorities = array_keys( $this->callbacks );
  282. }
  284. if ( $this->nesting_level > 0 ) {
  285. $this->resort_active_iterations();
  286. }
  287. }
  289. /**
  290. * Calls the callback functions that have been added to a filter hook.
  291. *
  292. * @since 4.7.0
  293. *
  294. * @param mixed $value The value to filter.
  295. * @param array $args Additional parameters to pass to the callback functions.
  296. * This array is expected to include $value at index 0.
  297. * @return mixed The filtered value after all hooked functions are applied to it.
  298. */
  299. public function apply_filters( $value, $args ) {
  300. if ( ! $this->callbacks ) {
  301. return $value;
  302. }
  304. $nesting_level = $this->nesting_level++;
  306. $this->iterations[ $nesting_level ] = $this->priorities;
  308. $num_args = count( $args );
  310. do {
  311. $this->current_priority[ $nesting_level ] = current( $this->iterations[ $nesting_level ] );
  313. $priority = $this->current_priority[ $nesting_level ];
  315. foreach ( $this->callbacks[ $priority ] as $the_ ) {
  316. if ( ! $this->doing_action ) {
  317. $args[0] = $value;
  318. }
  320. // Avoid the array_slice() if possible.
  321. if ( 0 === $the_['accepted_args'] ) {
  322. $value = call_user_func( $the_['function'] );
  323. } elseif ( $the_['accepted_args'] >= $num_args ) {
  324. $value = call_user_func_array( $the_['function'], $args );
  325. } else {
  326. $value = call_user_func_array( $the_['function'], array_slice( $args, 0, $the_['accepted_args'] ) );
  327. }
  328. }
  329. } while ( false !== next( $this->iterations[ $nesting_level ] ) );
  331. unset( $this->iterations[ $nesting_level ] );
  332. unset( $this->current_priority[ $nesting_level ] );
  334. --$this->nesting_level;
  336. return $value;
  337. }
  339. /**
  340. * Calls the callback functions that have been added to an action hook.
  341. *
  342. * @since 4.7.0
  343. *
  344. * @param array $args Parameters to pass to the callback functions.
  345. */
  346. public function do_action( $args ) {
  347. $this->doing_action = true;
  348. $this->apply_filters( '', $args );
  350. // If there are recursive calls to the current action, we haven't finished it until we get to the last one.
  351. if ( ! $this->nesting_level ) {
  352. $this->doing_action = false;
  353. }
  354. }
  356. /**
  357. * Processes the functions hooked into the 'all' hook.
  358. *
  359. * @since 4.7.0
  360. *
  361. * @param array $args Arguments to pass to the hook callbacks. Passed by reference.
  362. */
  363. public function do_all_hook( &$args ) {
  364. $nesting_level = $this->nesting_level++;
  365. $this->iterations[ $nesting_level ] = $this->priorities;
  367. do {
  368. $priority = current( $this->iterations[ $nesting_level ] );
  370. foreach ( $this->callbacks[ $priority ] as $the_ ) {
  371. call_user_func_array( $the_['function'], $args );
  372. }
  373. } while ( false !== next( $this->iterations[ $nesting_level ] ) );
  375. unset( $this->iterations[ $nesting_level ] );
  376. --$this->nesting_level;
  377. }
  379. /**
  380. * Return the current priority level of the currently running iteration of the hook.
  381. *
  382. * @since 4.7.0
  383. *
  384. * @return int|false If the hook is running, return the current priority level.
  385. * If it isn't running, return false.
  386. */
  387. public function current_priority() {
  388. if ( false === current( $this->iterations ) ) {
  389. return false;
  390. }
  392. return current( current( $this->iterations ) );
  393. }
  395. /**
  396. * Normalizes filters set up before WordPress has initialized to WP_Hook objects.
  397. *
  398. * The `$filters` parameter should be an array keyed by hook name, with values
  399. * containing either:
  400. *
  401. * - A `WP_Hook` instance
  402. * - An array of callbacks keyed by their priorities
  403. *
  404. * Examples:
  405. *
  406. * $filters = array(
  407. * 'wp_fatal_error_handler_enabled' => array(
  408. * 10 => array(
  409. * array(
  410. * 'accepted_args' => 0,
  411. * 'function' => function() {
  412. * return false;
  413. * },
  414. * ),
  415. * ),
  416. * ),
  417. * );
  418. *
  419. * @since 4.7.0
  420. *
  421. * @param array $filters Filters to normalize. See documentation above for details.
  422. * @return WP_Hook[] Array of normalized filters.
  423. */
  424. public static function build_preinitialized_hooks( $filters ) {
  425. /** @var WP_Hook[] $normalized */
  426. $normalized = array();
  428. foreach ( $filters as $hook_name => $callback_groups ) {
  429. if ( $callback_groups instanceof WP_Hook ) {
  430. $normalized[ $hook_name ] = $callback_groups;
  431. continue;
  432. }
  434. $hook = new WP_Hook();
  436. // Loop through callback groups.
  437. foreach ( $callback_groups as $priority => $callbacks ) {
  439. // Loop through callbacks.
  440. foreach ( $callbacks as $cb ) {
  441. $hook->add_filter( $hook_name, $cb['function'], $priority, $cb['accepted_args'] );
  442. }
  443. }
  445. $normalized[ $hook_name ] = $hook;
  446. }
  448. return $normalized;
  449. }
  451. /**
  452. * Determines whether an offset value exists.
  453. *
  454. * @since 4.7.0
  455. *
  456. * @link https://www.php.net/manual/en/arrayaccess.offsetexists.php
  457. *
  458. * @param mixed $offset An offset to check for.
  459. * @return bool True if the offset exists, false otherwise.
  460. */
  461. #[ReturnTypeWillChange]
  462. public function offsetExists( $offset ) {
  463. return isset( $this->callbacks[ $offset ] );
  464. }
  466. /**
  467. * Retrieves a value at a specified offset.
  468. *
  469. * @since 4.7.0
  470. *
  471. * @link https://www.php.net/manual/en/arrayaccess.offsetget.php
  472. *
  473. * @param mixed $offset The offset to retrieve.
  474. * @return mixed If set, the value at the specified offset, null otherwise.
  475. */
  476. #[ReturnTypeWillChange]
  477. public function offsetGet( $offset ) {
  478. return isset( $this->callbacks[ $offset ] ) ? $this->callbacks[ $offset ] : null;
  479. }
  481. /**
  482. * Sets a value at a specified offset.
  483. *
  484. * @since 4.7.0
  485. *
  486. * @link https://www.php.net/manual/en/arrayaccess.offsetset.php
  487. *
  488. * @param mixed $offset The offset to assign the value to.
  489. * @param mixed $value The value to set.
  490. */
  491. #[ReturnTypeWillChange]
  492. public function offsetSet( $offset, $value ) {
  493. if ( is_null( $offset ) ) {
  494. $this->callbacks[] = $value;
  495. } else {
  496. $this->callbacks[ $offset ] = $value;
  497. }
  499. $this->priorities = array_keys( $this->callbacks );
  500. }
  502. /**
  503. * Unsets a specified offset.
  504. *
  505. * @since 4.7.0
  506. *
  507. * @link https://www.php.net/manual/en/arrayaccess.offsetunset.php
  508. *
  509. * @param mixed $offset The offset to unset.
  510. */
  511. #[ReturnTypeWillChange]
  512. public function offsetUnset( $offset ) {
  513. unset( $this->callbacks[ $offset ] );
  514. $this->priorities = array_keys( $this->callbacks );
  515. }
  517. /**
  518. * Returns the current element.
  519. *
  520. * @since 4.7.0
  521. *
  522. * @link https://www.php.net/manual/en/iterator.current.php
  523. *
  524. * @return array Of callbacks at current priority.
  525. */
  526. #[ReturnTypeWillChange]
  527. public function current() {
  528. return current( $this->callbacks );
  529. }
  531. /**
  532. * Moves forward to the next element.
  533. *
  534. * @since 4.7.0
  535. *
  536. * @link https://www.php.net/manual/en/iterator.next.php
  537. *
  538. * @return array Of callbacks at next priority.
  539. */
  540. #[ReturnTypeWillChange]
  541. public function next() {
  542. return next( $this->callbacks );
  543. }
  545. /**
  546. * Returns the key of the current element.
  547. *
  548. * @since 4.7.0
  549. *
  550. * @link https://www.php.net/manual/en/iterator.key.php
  551. *
  552. * @return mixed Returns current priority on success, or NULL on failure
  553. */
  554. #[ReturnTypeWillChange]
  555. public function key() {
  556. return key( $this->callbacks );
  557. }
  559. /**
  560. * Checks if current position is valid.
  561. *
  562. * @since 4.7.0
  563. *
  564. * @link https://www.php.net/manual/en/iterator.valid.php
  565. *
  566. * @return bool Whether the current position is valid.
  567. */
  568. #[ReturnTypeWillChange]
  569. public function valid() {
  570. return key( $this->callbacks ) !== null;
  571. }
  573. /**
  574. * Rewinds the Iterator to the first element.
  575. *
  576. * @since 4.7.0
  577. *
  578. * @link https://www.php.net/manual/en/iterator.rewind.php
  579. */
  580. #[ReturnTypeWillChange]
  581. public function rewind() {
  582. reset( $this->callbacks );
  583. }
  584. }