public/blog/wp-includes/plugin.php line 482

  1. <?php
  2. /**
  3.  * The plugin API is located in this file, which allows for creating actions
  4.  * and filters and hooking functions, and methods. The functions or methods will
  5.  * then be run when the action or filter is called.
  6.  *
  7.  * The API callback examples reference functions, but can be methods of classes.
  8.  * To hook methods, you'll need to pass an array one of two ways.
  9.  *
  10.  * Any of the syntaxes explained in the PHP documentation for the
  11.  * {@link https://www.php.net/manual/en/language.pseudo-types.php#language.types.callback 'callback'}
  12.  * type are valid.
  13.  *
  14.  * Also see the {@link https://developer.wordpress.org/plugins/ Plugin API} for
  15.  * more information and examples on how to use a lot of these functions.
  16.  *
  17.  * This file should have no external dependencies.
  18.  *
  19.  * @package WordPress
  20.  * @subpackage Plugin
  21.  * @since 1.5.0
  22.  */
  24. // Initialize the filter globals.
  25. require __DIR__ . '/class-wp-hook.php';
  27. /** @var WP_Hook[] $wp_filter */
  28. global $wp_filter;
  30. /** @var int[] $wp_actions */
  31. global $wp_actions;
  33. /** @var int[] $wp_filters */
  34. global $wp_filters;
  36. /** @var string[] $wp_current_filter */
  37. global $wp_current_filter;
  39. if ( $wp_filter ) {
  40.     $wp_filter = WP_Hook::build_preinitialized_hooks( $wp_filter );
  41. } else {
  42.     $wp_filter = array();
  43. }
  45. if ( ! isset( $wp_actions ) ) {
  46.     $wp_actions = array();
  47. }
  49. if ( ! isset( $wp_filters ) ) {
  50.     $wp_filters = array();
  51. }
  53. if ( ! isset( $wp_current_filter ) ) {
  54.     $wp_current_filter = array();
  55. }
  57. /**
  58.  * Adds a callback function to a filter hook.
  59.  *
  60.  * WordPress offers filter hooks to allow plugins to modify
  61.  * various types of internal data at runtime.
  62.  *
  63.  * A plugin can modify data by binding a callback to a filter hook. When the filter
  64.  * is later applied, each bound callback is run in order of priority, and given
  65.  * the opportunity to modify a value by returning a new value.
  66.  *
  67.  * The following example shows how a callback function is bound to a filter hook.
  68.  *
  69.  * Note that `$example` is passed to the callback, (maybe) modified, then returned:
  70.  *
  71.  *     function example_callback( $example ) {
  72.  *         // Maybe modify $example in some way.
  73.  *         return $example;
  74.  *     }
  75.  *     add_filter( 'example_filter', 'example_callback' );
  76.  *
  77.  * Bound callbacks can accept from none to the total number of arguments passed as parameters
  78.  * in the corresponding apply_filters() call.
  79.  *
  80.  * In other words, if an apply_filters() call passes four total arguments, callbacks bound to
  81.  * it can accept none (the same as 1) of the arguments or up to four. The important part is that
  82.  * the `$accepted_args` value must reflect the number of arguments the bound callback *actually*
  83.  * opted to accept. If no arguments were accepted by the callback that is considered to be the
  84.  * same as accepting 1 argument. For example:
  85.  *
  86.  *     // Filter call.
  87.  *     $value = apply_filters( 'hook', $value, $arg2, $arg3 );
  88.  *
  89.  *     // Accepting zero/one arguments.
  90.  *     function example_callback() {
  91.  *         ...
  92.  *         return 'some value';
  93.  *     }
  94.  *     add_filter( 'hook', 'example_callback' ); // Where $priority is default 10, $accepted_args is default 1.
  95.  *
  96.  *     // Accepting two arguments (three possible).
  97.  *     function example_callback( $value, $arg2 ) {
  98.  *         ...
  99.  *         return $maybe_modified_value;
  100.  *     }
  101.  *     add_filter( 'hook', 'example_callback', 10, 2 ); // Where $priority is 10, $accepted_args is 2.
  102.  *
  103.  * *Note:* The function will return true whether or not the callback is valid.
  104.  * It is up to you to take care. This is done for optimization purposes, so
  105.  * everything is as quick as possible.
  106.  *
  107.  * @since 0.71
  108.  *
  109.  * @global WP_Hook[] $wp_filter A multidimensional array of all hooks and the callbacks hooked to them.
  110.  *
  111.  * @param string   $hook_name     The name of the filter to add the callback to.
  112.  * @param callable $callback      The callback to be run when the filter is applied.
  113.  * @param int      $priority      Optional. Used to specify the order in which the functions
  114.  *                                associated with a particular filter are executed.
  115.  *                                Lower numbers correspond with earlier execution,
  116.  *                                and functions with the same priority are executed
  117.  *                                in the order in which they were added to the filter. Default 10.
  118.  * @param int      $accepted_args Optional. The number of arguments the function accepts. Default 1.
  119.  * @return true Always returns true.
  120.  */
  121. function add_filter( $hook_name, $callback, $priority = 10, $accepted_args = 1 ) {
  122.     global $wp_filter;
  124.     if ( ! isset( $wp_filter[ $hook_name ] ) ) {
  125.         $wp_filter[ $hook_name ] = new WP_Hook();
  126.     }
  128.     $wp_filter[ $hook_name ]->add_filter( $hook_name, $callback, $priority, $accepted_args );
  130.     return true;
  131. }
  133. /**
  134.  * Calls the callback functions that have been added to a filter hook.
  135.  *
  136.  * This function invokes all functions attached to filter hook `$hook_name`.
  137.  * It is possible to create new filter hooks by simply calling this function,
  138.  * specifying the name of the new hook using the `$hook_name` parameter.
  139.  *
  140.  * The function also allows for multiple additional arguments to be passed to hooks.
  141.  *
  142.  * Example usage:
  143.  *
  144.  *     // The filter callback function.
  145.  *     function example_callback( $string, $arg1, $arg2 ) {
  146.  *         // (maybe) modify $string.
  147.  *         return $string;
  148.  *     }
  149.  *     add_filter( 'example_filter', 'example_callback', 10, 3 );
  150.  *
  151.  *     /*
  152.  *      * Apply the filters by calling the 'example_callback()' function
  153.  *      * that's hooked onto `example_filter` above.
  154.  *      *
  155.  *      * - 'example_filter' is the filter hook.
  156.  *      * - 'filter me' is the value being filtered.
  157.  *      * - $arg1 and $arg2 are the additional arguments passed to the callback.
  158.  *     $value = apply_filters( 'example_filter', 'filter me', $arg1, $arg2 );
  159.  *
  160.  * @since 0.71
  161.  * @since 6.0.0 Formalized the existing and already documented `...$args` parameter
  162.  *              by adding it to the function signature.
  163.  *
  164.  * @global WP_Hook[] $wp_filter         Stores all of the filters and actions.
  165.  * @global int[]     $wp_filters        Stores the number of times each filter was triggered.
  166.  * @global string[]  $wp_current_filter Stores the list of current filters with the current one last.
  167.  *
  168.  * @param string $hook_name The name of the filter hook.
  169.  * @param mixed  $value     The value to filter.
  170.  * @param mixed  ...$args   Optional. Additional parameters to pass to the callback functions.
  171.  * @return mixed The filtered value after all hooked functions are applied to it.
  172.  */
  173. function apply_filters( $hook_name, $value, ...$args ) {
  174.     global $wp_filter, $wp_filters, $wp_current_filter;
  176.     if ( ! isset( $wp_filters[ $hook_name ] ) ) {
  177.         $wp_filters[ $hook_name ] = 1;
  178.     } else {
  179.         ++$wp_filters[ $hook_name ];
  180.     }
  182.     // Do 'all' actions first.
  183.     if ( isset( $wp_filter['all'] ) ) {
  184.         $wp_current_filter[] = $hook_name;
  186.         $all_args = func_get_args(); // phpcs:ignore PHPCompatibility.FunctionUse.ArgumentFunctionsReportCurrentValue.NeedsInspection
  187.         _wp_call_all_hook( $all_args );
  188.     }
  190.     if ( ! isset( $wp_filter[ $hook_name ] ) ) {
  191.         if ( isset( $wp_filter['all'] ) ) {
  192.             array_pop( $wp_current_filter );
  193.         }
  195.         return $value;
  196.     }
  198.     if ( ! isset( $wp_filter['all'] ) ) {
  199.         $wp_current_filter[] = $hook_name;
  200.     }
  202.     // Pass the value to WP_Hook.
  203.     array_unshift( $args, $value );
  205.     $filtered = $wp_filter[ $hook_name ]->apply_filters( $value, $args );
  207.     array_pop( $wp_current_filter );
  209.     return $filtered;
  210. }
  212. /**
  213.  * Calls the callback functions that have been added to a filter hook, specifying arguments in an array.
  214.  *
  215.  * @since 3.0.0
  216.  *
  217.  * @see apply_filters() This function is identical, but the arguments passed to the
  218.  *                      functions hooked to `$hook_name` are supplied using an array.
  219.  *
  220.  * @global WP_Hook[] $wp_filter         Stores all of the filters and actions.
  221.  * @global int[]     $wp_filters        Stores the number of times each filter was triggered.
  222.  * @global string[]  $wp_current_filter Stores the list of current filters with the current one last.
  223.  *
  224.  * @param string $hook_name The name of the filter hook.
  225.  * @param array  $args      The arguments supplied to the functions hooked to `$hook_name`.
  226.  * @return mixed The filtered value after all hooked functions are applied to it.
  227.  */
  228. function apply_filters_ref_array( $hook_name, $args ) {
  229.     global $wp_filter, $wp_filters, $wp_current_filter;
  231.     if ( ! isset( $wp_filters[ $hook_name ] ) ) {
  232.         $wp_filters[ $hook_name ] = 1;
  233.     } else {
  234.         ++$wp_filters[ $hook_name ];
  235.     }
  237.     // Do 'all' actions first.
  238.     if ( isset( $wp_filter['all'] ) ) {
  239.         $wp_current_filter[] = $hook_name;
  240.         $all_args            = func_get_args(); // phpcs:ignore PHPCompatibility.FunctionUse.ArgumentFunctionsReportCurrentValue.NeedsInspection
  241.         _wp_call_all_hook( $all_args );
  242.     }
  244.     if ( ! isset( $wp_filter[ $hook_name ] ) ) {
  245.         if ( isset( $wp_filter['all'] ) ) {
  246.             array_pop( $wp_current_filter );
  247.         }
  249.         return $args[0];
  250.     }
  252.     if ( ! isset( $wp_filter['all'] ) ) {
  253.         $wp_current_filter[] = $hook_name;
  254.     }
  256.     $filtered = $wp_filter[ $hook_name ]->apply_filters( $args[0], $args );
  258.     array_pop( $wp_current_filter );
  260.     return $filtered;
  261. }
  263. /**
  264.  * Checks if any filter has been registered for a hook.
  265.  *
  266.  * When using the `$callback` argument, this function may return a non-boolean value
  267.  * that evaluates to false (e.g. 0), so use the `===` operator for testing the return value.
  268.  *
  269.  * @since 2.5.0
  270.  *
  271.  * @global WP_Hook[] $wp_filter Stores all of the filters and actions.
  272.  *
  273.  * @param string                      $hook_name The name of the filter hook.
  274.  * @param callable|string|array|false $callback  Optional. The callback to check for.
  275.  *                                               This function can be called unconditionally to speculatively check
  276.  *                                               a callback that may or may not exist. Default false.
  277.  * @return bool|int If `$callback` is omitted, returns boolean for whether the hook has
  278.  *                  anything registered. When checking a specific function, the priority
  279.  *                  of that hook is returned, or false if the function is not attached.
  280.  */
  281. function has_filter( $hook_name, $callback = false ) {
  282.     global $wp_filter;
  284.     if ( ! isset( $wp_filter[ $hook_name ] ) ) {
  285.         return false;
  286.     }
  288.     return $wp_filter[ $hook_name ]->has_filter( $hook_name, $callback );
  289. }
  291. /**
  292.  * Removes a callback function from a filter hook.
  293.  *
  294.  * This can be used to remove default functions attached to a specific filter
  295.  * hook and possibly replace them with a substitute.
  296.  *
  297.  * To remove a hook, the `$callback` and `$priority` arguments must match
  298.  * when the hook was added. This goes for both filters and actions. No warning
  299.  * will be given on removal failure.
  300.  *
  301.  * @since 1.2.0
  302.  *
  303.  * @global WP_Hook[] $wp_filter Stores all of the filters and actions.
  304.  *
  305.  * @param string                $hook_name The filter hook to which the function to be removed is hooked.
  306.  * @param callable|string|array $callback  The callback to be removed from running when the filter is applied.
  307.  *                                         This function can be called unconditionally to speculatively remove
  308.  *                                         a callback that may or may not exist.
  309.  * @param int                   $priority  Optional. The exact priority used when adding the original
  310.  *                                         filter callback. Default 10.
  311.  * @return bool Whether the function existed before it was removed.
  312.  */
  313. function remove_filter( $hook_name, $callback, $priority = 10 ) {
  314.     global $wp_filter;
  316.     $r = false;
  318.     if ( isset( $wp_filter[ $hook_name ] ) ) {
  319.         $r = $wp_filter[ $hook_name ]->remove_filter( $hook_name, $callback, $priority );
  321.         if ( ! $wp_filter[ $hook_name ]->callbacks ) {
  322.             unset( $wp_filter[ $hook_name ] );
  323.         }
  324.     }
  326.     return $r;
  327. }
  329. /**
  330.  * Removes all of the callback functions from a filter hook.
  331.  *
  332.  * @since 2.7.0
  333.  *
  334.  * @global WP_Hook[] $wp_filter Stores all of the filters and actions.
  335.  *
  336.  * @param string    $hook_name The filter to remove callbacks from.
  337.  * @param int|false $priority  Optional. The priority number to remove them from.
  338.  *                             Default false.
  339.  * @return true Always returns true.
  340.  */
  341. function remove_all_filters( $hook_name, $priority = false ) {
  342.     global $wp_filter;
  344.     if ( isset( $wp_filter[ $hook_name ] ) ) {
  345.         $wp_filter[ $hook_name ]->remove_all_filters( $priority );
  347.         if ( ! $wp_filter[ $hook_name ]->has_filters() ) {
  348.             unset( $wp_filter[ $hook_name ] );
  349.         }
  350.     }
  352.     return true;
  353. }
  355. /**
  356.  * Retrieves the name of the current filter hook.
  357.  *
  358.  * @since 2.5.0
  359.  *
  360.  * @global string[] $wp_current_filter Stores the list of current filters with the current one last
  361.  *
  362.  * @return string Hook name of the current filter.
  363.  */
  364. function current_filter() {
  365.     global $wp_current_filter;
  367.     return end( $wp_current_filter );
  368. }
  370. /**
  371.  * Returns whether or not a filter hook is currently being processed.
  372.  *
  373.  * The function current_filter() only returns the most recent filter being executed.
  374.  * did_filter() returns the number of times a filter has been applied during
  375.  * the current request.
  376.  *
  377.  * This function allows detection for any filter currently being executed
  378.  * (regardless of whether it's the most recent filter to fire, in the case of
  379.  * hooks called from hook callbacks) to be verified.
  380.  *
  381.  * @since 3.9.0
  382.  *
  383.  * @see current_filter()
  384.  * @see did_filter()
  385.  * @global string[] $wp_current_filter Current filter.
  386.  *
  387.  * @param string|null $hook_name Optional. Filter hook to check. Defaults to null,
  388.  *                               which checks if any filter is currently being run.
  389.  * @return bool Whether the filter is currently in the stack.
  390.  */
  391. function doing_filter( $hook_name = null ) {
  392.     global $wp_current_filter;
  394.     if ( null === $hook_name ) {
  395.         return ! empty( $wp_current_filter );
  396.     }
  398.     return in_array( $hook_name, $wp_current_filter, true );
  399. }
  401. /**
  402.  * Retrieves the number of times a filter has been applied during the current request.
  403.  *
  404.  * @since 6.1.0
  405.  *
  406.  * @global int[] $wp_filters Stores the number of times each filter was triggered.
  407.  *
  408.  * @param string $hook_name The name of the filter hook.
  409.  * @return int The number of times the filter hook has been applied.
  410.  */
  411. function did_filter( $hook_name ) {
  412.     global $wp_filters;
  414.     if ( ! isset( $wp_filters[ $hook_name ] ) ) {
  415.         return 0;
  416.     }
  418.     return $wp_filters[ $hook_name ];
  419. }
  421. /**
  422.  * Adds a callback function to an action hook.
  423.  *
  424.  * Actions are the hooks that the WordPress core launches at specific points
  425.  * during execution, or when specific events occur. Plugins can specify that
  426.  * one or more of its PHP functions are executed at these points, using the
  427.  * Action API.
  428.  *
  429.  * @since 1.2.0
  430.  *
  431.  * @param string   $hook_name       The name of the action to add the callback to.
  432.  * @param callable $callback        The callback to be run when the action is called.
  433.  * @param int      $priority        Optional. Used to specify the order in which the functions
  434.  *                                  associated with a particular action are executed.
  435.  *                                  Lower numbers correspond with earlier execution,
  436.  *                                  and functions with the same priority are executed
  437.  *                                  in the order in which they were added to the action. Default 10.
  438.  * @param int      $accepted_args   Optional. The number of arguments the function accepts. Default 1.
  439.  * @return true Always returns true.
  440.  */
  441. function add_action( $hook_name, $callback, $priority = 10, $accepted_args = 1 ) {
  442.     return add_filter( $hook_name, $callback, $priority, $accepted_args );
  443. }
  445. /**
  446.  * Calls the callback functions that have been added to an action hook.
  447.  *
  448.  * This function invokes all functions attached to action hook `$hook_name`.
  449.  * It is possible to create new action hooks by simply calling this function,
  450.  * specifying the name of the new hook using the `$hook_name` parameter.
  451.  *
  452.  * You can pass extra arguments to the hooks, much like you can with `apply_filters()`.
  453.  *
  454.  * Example usage:
  455.  *
  456.  *     // The action callback function.
  457.  *     function example_callback( $arg1, $arg2 ) {
  458.  *         // (maybe) do something with the args.
  459.  *     }
  460.  *     add_action( 'example_action', 'example_callback', 10, 2 );
  461.  *
  462.  *     /*
  463.  *      * Trigger the actions by calling the 'example_callback()' function
  464.  *      * that's hooked onto `example_action` above.
  465.  *      *
  466.  *      * - 'example_action' is the action hook.
  467.  *      * - $arg1 and $arg2 are the additional arguments passed to the callback.
  468.  *     do_action( 'example_action', $arg1, $arg2 );
  469.  *
  470.  * @since 1.2.0
  471.  * @since 5.3.0 Formalized the existing and already documented `...$arg` parameter
  472.  *              by adding it to the function signature.
  473.  *
  474.  * @global WP_Hook[] $wp_filter         Stores all of the filters and actions.
  475.  * @global int[]     $wp_actions        Stores the number of times each action was triggered.
  476.  * @global string[]  $wp_current_filter Stores the list of current filters with the current one last.
  477.  *
  478.  * @param string $hook_name The name of the action to be executed.
  479.  * @param mixed  ...$arg    Optional. Additional arguments which are passed on to the
  480.  *                          functions hooked to the action. Default empty.
  481.  */
  482. function do_action( $hook_name, ...$arg ) {
  483.     global $wp_filter, $wp_actions, $wp_current_filter;
  485.     if ( ! isset( $wp_actions[ $hook_name ] ) ) {
  486.         $wp_actions[ $hook_name ] = 1;
  487.     } else {
  488.         ++$wp_actions[ $hook_name ];
  489.     }
  491.     // Do 'all' actions first.
  492.     if ( isset( $wp_filter['all'] ) ) {
  493.         $wp_current_filter[] = $hook_name;
  494.         $all_args            = func_get_args(); // phpcs:ignore PHPCompatibility.FunctionUse.ArgumentFunctionsReportCurrentValue.NeedsInspection
  495.         _wp_call_all_hook( $all_args );
  496.     }
  498.     if ( ! isset( $wp_filter[ $hook_name ] ) ) {
  499.         if ( isset( $wp_filter['all'] ) ) {
  500.             array_pop( $wp_current_filter );
  501.         }
  503.         return;
  504.     }
  506.     if ( ! isset( $wp_filter['all'] ) ) {
  507.         $wp_current_filter[] = $hook_name;
  508.     }
  510.     if ( empty( $arg ) ) {
  511.         $arg[] = '';
  512.     } elseif ( is_array( $arg[0] ) && 1 === count( $arg[0] ) && isset( $arg[0][0] ) && is_object( $arg[0][0] ) ) {
  513.         // Backward compatibility for PHP4-style passing of `array( &$this )` as action `$arg`.
  514.         $arg[0] = $arg[0][0];
  515.     }
  517.     $wp_filter[ $hook_name ]->do_action( $arg );
  519.     array_pop( $wp_current_filter );
  520. }
  522. /**
  523.  * Calls the callback functions that have been added to an action hook, specifying arguments in an array.
  524.  *
  525.  * @since 2.1.0
  526.  *
  527.  * @see do_action() This function is identical, but the arguments passed to the
  528.  *                  functions hooked to `$hook_name` are supplied using an array.
  529.  *
  530.  * @global WP_Hook[] $wp_filter         Stores all of the filters and actions.
  531.  * @global int[]     $wp_actions        Stores the number of times each action was triggered.
  532.  * @global string[]  $wp_current_filter Stores the list of current filters with the current one last.
  533.  *
  534.  * @param string $hook_name The name of the action to be executed.
  535.  * @param array  $args      The arguments supplied to the functions hooked to `$hook_name`.
  536.  */
  537. function do_action_ref_array( $hook_name, $args ) {
  538.     global $wp_filter, $wp_actions, $wp_current_filter;
  540.     if ( ! isset( $wp_actions[ $hook_name ] ) ) {
  541.         $wp_actions[ $hook_name ] = 1;
  542.     } else {
  543.         ++$wp_actions[ $hook_name ];
  544.     }
  546.     // Do 'all' actions first.
  547.     if ( isset( $wp_filter['all'] ) ) {
  548.         $wp_current_filter[] = $hook_name;
  549.         $all_args            = func_get_args(); // phpcs:ignore PHPCompatibility.FunctionUse.ArgumentFunctionsReportCurrentValue.NeedsInspection
  550.         _wp_call_all_hook( $all_args );
  551.     }
  553.     if ( ! isset( $wp_filter[ $hook_name ] ) ) {
  554.         if ( isset( $wp_filter['all'] ) ) {
  555.             array_pop( $wp_current_filter );
  556.         }
  558.         return;
  559.     }
  561.     if ( ! isset( $wp_filter['all'] ) ) {
  562.         $wp_current_filter[] = $hook_name;
  563.     }
  565.     $wp_filter[ $hook_name ]->do_action( $args );
  567.     array_pop( $wp_current_filter );
  568. }
  570. /**
  571.  * Checks if any action has been registered for a hook.
  572.  *
  573.  * When using the `$callback` argument, this function may return a non-boolean value
  574.  * that evaluates to false (e.g. 0), so use the `===` operator for testing the return value.
  575.  *
  576.  * @since 2.5.0
  577.  *
  578.  * @see has_filter() This function is an alias of has_filter().
  579.  *
  580.  * @param string                      $hook_name The name of the action hook.
  581.  * @param callable|string|array|false $callback  Optional. The callback to check for.
  582.  *                                               This function can be called unconditionally to speculatively check
  583.  *                                               a callback that may or may not exist. Default false.
  584.  * @return bool|int If `$callback` is omitted, returns boolean for whether the hook has
  585.  *                  anything registered. When checking a specific function, the priority
  586.  *                  of that hook is returned, or false if the function is not attached.
  587.  */
  588. function has_action( $hook_name, $callback = false ) {
  589.     return has_filter( $hook_name, $callback );
  590. }
  592. /**
  593.  * Removes a callback function from an action hook.
  594.  *
  595.  * This can be used to remove default functions attached to a specific action
  596.  * hook and possibly replace them with a substitute.
  597.  *
  598.  * To remove a hook, the `$callback` and `$priority` arguments must match
  599.  * when the hook was added. This goes for both filters and actions. No warning
  600.  * will be given on removal failure.
  601.  *
  602.  * @since 1.2.0
  603.  *
  604.  * @param string                $hook_name The action hook to which the function to be removed is hooked.
  605.  * @param callable|string|array $callback  The name of the function which should be removed.
  606.  *                                         This function can be called unconditionally to speculatively remove
  607.  *                                         a callback that may or may not exist.
  608.  * @param int                   $priority  Optional. The exact priority used when adding the original
  609.  *                                         action callback. Default 10.
  610.  * @return bool Whether the function is removed.
  611.  */
  612. function remove_action( $hook_name, $callback, $priority = 10 ) {
  613.     return remove_filter( $hook_name, $callback, $priority );
  614. }
  616. /**
  617.  * Removes all of the callback functions from an action hook.
  618.  *
  619.  * @since 2.7.0
  620.  *
  621.  * @param string    $hook_name The action to remove callbacks from.
  622.  * @param int|false $priority  Optional. The priority number to remove them from.
  623.  *                             Default false.
  624.  * @return true Always returns true.
  625.  */
  626. function remove_all_actions( $hook_name, $priority = false ) {
  627.     return remove_all_filters( $hook_name, $priority );
  628. }
  630. /**
  631.  * Retrieves the name of the current action hook.
  632.  *
  633.  * @since 3.9.0
  634.  *
  635.  * @return string Hook name of the current action.
  636.  */
  637. function current_action() {
  638.     return current_filter();
  639. }
  641. /**
  642.  * Returns whether or not an action hook is currently being processed.
  643.  *
  644.  * The function current_action() only returns the most recent action being executed.
  645.  * did_action() returns the number of times an action has been fired during
  646.  * the current request.
  647.  *
  648.  * This function allows detection for any action currently being executed
  649.  * (regardless of whether it's the most recent action to fire, in the case of
  650.  * hooks called from hook callbacks) to be verified.
  651.  *
  652.  * @since 3.9.0
  653.  *
  654.  * @see current_action()
  655.  * @see did_action()
  656.  *
  657.  * @param string|null $hook_name Optional. Action hook to check. Defaults to null,
  658.  *                               which checks if any action is currently being run.
  659.  * @return bool Whether the action is currently in the stack.
  660.  */
  661. function doing_action( $hook_name = null ) {
  662.     return doing_filter( $hook_name );
  663. }
  665. /**
  666.  * Retrieves the number of times an action has been fired during the current request.
  667.  *
  668.  * @since 2.1.0
  669.  *
  670.  * @global int[] $wp_actions Stores the number of times each action was triggered.
  671.  *
  672.  * @param string $hook_name The name of the action hook.
  673.  * @return int The number of times the action hook has been fired.
  674.  */
  675. function did_action( $hook_name ) {
  676.     global $wp_actions;
  678.     if ( ! isset( $wp_actions[ $hook_name ] ) ) {
  679.         return 0;
  680.     }
  682.     return $wp_actions[ $hook_name ];
  683. }
  685. /**
  686.  * Fires functions attached to a deprecated filter hook.
  687.  *
  688.  * When a filter hook is deprecated, the apply_filters() call is replaced with
  689.  * apply_filters_deprecated(), which triggers a deprecation notice and then fires
  690.  * the original filter hook.
  691.  *
  692.  * Note: the value and extra arguments passed to the original apply_filters() call
  693.  * must be passed here to `$args` as an array. For example:
  694.  *
  695.  *     // Old filter.
  696.  *     return apply_filters( 'wpdocs_filter', $value, $extra_arg );
  697.  *
  698.  *     // Deprecated.
  699.  *     return apply_filters_deprecated( 'wpdocs_filter', array( $value, $extra_arg ), '4.9.0', 'wpdocs_new_filter' );
  700.  *
  701.  * @since 4.6.0
  702.  *
  703.  * @see _deprecated_hook()
  704.  *
  705.  * @param string $hook_name   The name of the filter hook.
  706.  * @param array  $args        Array of additional function arguments to be passed to apply_filters().
  707.  * @param string $version     The version of WordPress that deprecated the hook.
  708.  * @param string $replacement Optional. The hook that should have been used. Default empty.
  709.  * @param string $message     Optional. A message regarding the change. Default empty.
  710.  * @return mixed The filtered value after all hooked functions are applied to it.
  711.  */
  712. function apply_filters_deprecated( $hook_name, $args, $version, $replacement = '', $message = '' ) {
  713.     if ( ! has_filter( $hook_name ) ) {
  714.         return $args[0];
  715.     }
  717.     _deprecated_hook( $hook_name, $version, $replacement, $message );
  719.     return apply_filters_ref_array( $hook_name, $args );
  720. }
  722. /**
  723.  * Fires functions attached to a deprecated action hook.
  724.  *
  725.  * When an action hook is deprecated, the do_action() call is replaced with
  726.  * do_action_deprecated(), which triggers a deprecation notice and then fires
  727.  * the original hook.
  728.  *
  729.  * @since 4.6.0
  730.  *
  731.  * @see _deprecated_hook()
  732.  *
  733.  * @param string $hook_name   The name of the action hook.
  734.  * @param array  $args        Array of additional function arguments to be passed to do_action().
  735.  * @param string $version     The version of WordPress that deprecated the hook.
  736.  * @param string $replacement Optional. The hook that should have been used. Default empty.
  737.  * @param string $message     Optional. A message regarding the change. Default empty.
  738.  */
  739. function do_action_deprecated( $hook_name, $args, $version, $replacement = '', $message = '' ) {
  740.     if ( ! has_action( $hook_name ) ) {
  741.         return;
  742.     }
  744.     _deprecated_hook( $hook_name, $version, $replacement, $message );
  746.     do_action_ref_array( $hook_name, $args );
  747. }
  749. //
  750. // Functions for handling plugins.
  751. //
  753. /**
  754.  * Gets the basename of a plugin.
  755.  *
  756.  * This method extracts the name of a plugin from its filename.
  757.  *
  758.  * @since 1.5.0
  759.  *
  760.  * @global array $wp_plugin_paths
  761.  *
  762.  * @param string $file The filename of plugin.
  763.  * @return string The name of a plugin.
  764.  */
  765. function plugin_basename( $file ) {
  766.     global $wp_plugin_paths;
  768.     // $wp_plugin_paths contains normalized paths.
  769.     $file = wp_normalize_path( $file );
  771.     arsort( $wp_plugin_paths );
  773.     foreach ( $wp_plugin_paths as $dir => $realdir ) {
  774.         if ( str_starts_with( $file, $realdir ) ) {
  775.             $file = $dir . substr( $file, strlen( $realdir ) );
  776.         }
  777.     }
  779.     $plugin_dir    = wp_normalize_path( WP_PLUGIN_DIR );
  780.     $mu_plugin_dir = wp_normalize_path( WPMU_PLUGIN_DIR );
  782.     // Get relative path from plugins directory.
  783.     $file = preg_replace( '#^' . preg_quote( $plugin_dir, '#' ) . '/|^' . preg_quote( $mu_plugin_dir, '#' ) . '/#', '', $file );
  784.     $file = trim( $file, '/' );
  785.     return $file;
  786. }
  788. /**
  789.  * Register a plugin's real path.
  790.  *
  791.  * This is used in plugin_basename() to resolve symlinked paths.
  792.  *
  793.  * @since 3.9.0
  794.  *
  795.  * @see wp_normalize_path()
  796.  *
  797.  * @global array $wp_plugin_paths
  798.  *
  799.  * @param string $file Known path to the file.
  800.  * @return bool Whether the path was able to be registered.
  801.  */
  802. function wp_register_plugin_realpath( $file ) {
  803.     global $wp_plugin_paths;
  805.     // Normalize, but store as static to avoid recalculation of a constant value.
  806.     static $wp_plugin_path = null, $wpmu_plugin_path = null;
  808.     if ( ! isset( $wp_plugin_path ) ) {
  809.         $wp_plugin_path   = wp_normalize_path( WP_PLUGIN_DIR );
  810.         $wpmu_plugin_path = wp_normalize_path( WPMU_PLUGIN_DIR );
  811.     }
  813.     $plugin_path     = wp_normalize_path( dirname( $file ) );
  814.     $plugin_realpath = wp_normalize_path( dirname( realpath( $file ) ) );
  816.     if ( $plugin_path === $wp_plugin_path || $plugin_path === $wpmu_plugin_path ) {
  817.         return false;
  818.     }
  820.     if ( $plugin_path !== $plugin_realpath ) {
  821.         $wp_plugin_paths[ $plugin_path ] = $plugin_realpath;
  822.     }
  824.     return true;
  825. }
  827. /**
  828.  * Get the filesystem directory path (with trailing slash) for the plugin __FILE__ passed in.
  829.  *
  830.  * @since 2.8.0
  831.  *
  832.  * @param string $file The filename of the plugin (__FILE__).
  833.  * @return string the filesystem path of the directory that contains the plugin.
  834.  */
  835. function plugin_dir_path( $file ) {
  836.     return trailingslashit( dirname( $file ) );
  837. }
  839. /**
  840.  * Get the URL directory path (with trailing slash) for the plugin __FILE__ passed in.
  841.  *
  842.  * @since 2.8.0
  843.  *
  844.  * @param string $file The filename of the plugin (__FILE__).
  845.  * @return string the URL path of the directory that contains the plugin.
  846.  */
  847. function plugin_dir_url( $file ) {
  848.     return trailingslashit( plugins_url( '', $file ) );
  849. }
  851. /**
  852.  * Set the activation hook for a plugin.
  853.  *
  854.  * When a plugin is activated, the action 'activate_PLUGINNAME' hook is
  855.  * called. In the name of this hook, PLUGINNAME is replaced with the name
  856.  * of the plugin, including the optional subdirectory. For example, when the
  857.  * plugin is located in wp-content/plugins/sampleplugin/sample.php, then
  858.  * the name of this hook will become 'activate_sampleplugin/sample.php'.
  859.  *
  860.  * When the plugin consists of only one file and is (as by default) located at
  861.  * wp-content/plugins/sample.php the name of this hook will be
  862.  * 'activate_sample.php'.
  863.  *
  864.  * @since 2.0.0
  865.  *
  866.  * @param string   $file     The filename of the plugin including the path.
  867.  * @param callable $callback The function hooked to the 'activate_PLUGIN' action.
  868.  */
  869. function register_activation_hook( $file, $callback ) {
  870.     $file = plugin_basename( $file );
  871.     add_action( 'activate_' . $file, $callback );
  872. }
  874. /**
  875.  * Sets the deactivation hook for a plugin.
  876.  *
  877.  * When a plugin is deactivated, the action 'deactivate_PLUGINNAME' hook is
  878.  * called. In the name of this hook, PLUGINNAME is replaced with the name
  879.  * of the plugin, including the optional subdirectory. For example, when the
  880.  * plugin is located in wp-content/plugins/sampleplugin/sample.php, then
  881.  * the name of this hook will become 'deactivate_sampleplugin/sample.php'.
  882.  *
  883.  * When the plugin consists of only one file and is (as by default) located at
  884.  * wp-content/plugins/sample.php the name of this hook will be
  885.  * 'deactivate_sample.php'.
  886.  *
  887.  * @since 2.0.0
  888.  *
  889.  * @param string   $file     The filename of the plugin including the path.
  890.  * @param callable $callback The function hooked to the 'deactivate_PLUGIN' action.
  891.  */
  892. function register_deactivation_hook( $file, $callback ) {
  893.     $file = plugin_basename( $file );
  894.     add_action( 'deactivate_' . $file, $callback );
  895. }
  897. /**
  898.  * Sets the uninstallation hook for a plugin.
  899.  *
  900.  * Registers the uninstall hook that will be called when the user clicks on the
  901.  * uninstall link that calls for the plugin to uninstall itself. The link won't
  902.  * be active unless the plugin hooks into the action.
  903.  *
  904.  * The plugin should not run arbitrary code outside of functions, when
  905.  * registering the uninstall hook. In order to run using the hook, the plugin
  906.  * will have to be included, which means that any code laying outside of a
  907.  * function will be run during the uninstallation process. The plugin should not
  908.  * hinder the uninstallation process.
  909.  *
  910.  * If the plugin can not be written without running code within the plugin, then
  911.  * the plugin should create a file named 'uninstall.php' in the base plugin
  912.  * folder. This file will be called, if it exists, during the uninstallation process
  913.  * bypassing the uninstall hook. The plugin, when using the 'uninstall.php'
  914.  * should always check for the 'WP_UNINSTALL_PLUGIN' constant, before
  915.  * executing.
  916.  *
  917.  * @since 2.7.0
  918.  *
  919.  * @param string   $file     Plugin file.
  920.  * @param callable $callback The callback to run when the hook is called. Must be
  921.  *                           a static method or function.
  922.  */
  923. function register_uninstall_hook( $file, $callback ) {
  924.     if ( is_array( $callback ) && is_object( $callback[0] ) ) {
  925.         _doing_it_wrong( __FUNCTION__, __( 'Only a static class method or function can be used in an uninstall hook.' ), '3.1.0' );
  926.         return;
  927.     }
  929.     /*
  930.      * The option should not be autoloaded, because it is not needed in most
  931.      * cases. Emphasis should be put on using the 'uninstall.php' way of
  932.      * uninstalling the plugin.
  933.      */
  934.     $uninstallable_plugins = (array) get_option( 'uninstall_plugins' );
  935.     $plugin_basename       = plugin_basename( $file );
  937.     if ( ! isset( $uninstallable_plugins[ $plugin_basename ] ) || $uninstallable_plugins[ $plugin_basename ] !== $callback ) {
  938.         $uninstallable_plugins[ $plugin_basename ] = $callback;
  939.         update_option( 'uninstall_plugins', $uninstallable_plugins );
  940.     }
  941. }
  943. /**
  944.  * Calls the 'all' hook, which will process the functions hooked into it.
  945.  *
  946.  * The 'all' hook passes all of the arguments or parameters that were used for
  947.  * the hook, which this function was called for.
  948.  *
  949.  * This function is used internally for apply_filters(), do_action(), and
  950.  * do_action_ref_array() and is not meant to be used from outside those
  951.  * functions. This function does not check for the existence of the all hook, so
  952.  * it will fail unless the all hook exists prior to this function call.
  953.  *
  954.  * @since 2.5.0
  955.  * @access private
  956.  *
  957.  * @global WP_Hook[] $wp_filter Stores all of the filters and actions.
  958.  *
  959.  * @param array $args The collected parameters from the hook that was called.
  960.  */
  961. function _wp_call_all_hook( $args ) {
  962.     global $wp_filter;
  964.     $wp_filter['all']->do_all_hook( $args );
  965. }
  967. /**
  968.  * Builds a unique string ID for a hook callback function.
  969.  *
  970.  * Functions and static method callbacks are just returned as strings and
  971.  * shouldn't have any speed penalty.
  972.  *
  973.  * @link https://core.trac.wordpress.org/ticket/3875
  974.  *
  975.  * @since 2.2.3
  976.  * @since 5.3.0 Removed workarounds for spl_object_hash().
  977.  *              `$hook_name` and `$priority` are no longer used,
  978.  *              and the function always returns a string.
  979.  *
  980.  * @access private
  981.  *
  982.  * @param string                $hook_name Unused. The name of the filter to build ID for.
  983.  * @param callable|string|array $callback  The callback to generate ID for. The callback may
  984.  *                                         or may not exist.
  985.  * @param int                   $priority  Unused. The order in which the functions
  986.  *                                         associated with a particular action are executed.
  987.  * @return string Unique function ID for usage as array key.
  988.  */
  989. function _wp_filter_build_unique_id( $hook_name, $callback, $priority ) {
  990.     if ( is_string( $callback ) ) {
  991.         return $callback;
  992.     }
  994.     if ( is_object( $callback ) ) {
  995.         // Closures are currently implemented as objects.
  996.         $callback = array( $callback, '' );
  997.     } else {
  998.         $callback = (array) $callback;
  999.     }
  1001.     if ( is_object( $callback[0] ) ) {
  1002.         // Object class calling.
  1003.         return spl_object_hash( $callback[0] ) . $callback[1];
  1004.     } elseif ( is_string( $callback[0] ) ) {
  1005.         // Static calling.
  1006.         return $callback[0] . '::' . $callback[1];
  1007.     }
  1008. }