[Summary view] [Print] [Text view]

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