[ Index ]

PHP Cross Reference of BackPress

title

Body

[close]

/includes/ -> functions.plugin-api.php (source)

   1  <?php
   2  // Last sync [WP14924]
   3  
   4  /**
   5   * The plugin API is located in this file, which allows for creating actions
   6   * and filters and hooking functions, and methods. The functions or methods will
   7   * then be run when the action or filter is called.
   8   *
   9   * The API callback examples reference functions, but can be methods of classes.
  10   * To hook methods, you'll need to pass an array one of two ways.
  11   *
  12   * Any of the syntaxes explained in the PHP documentation for the
  13   * {@link http://us2.php.net/manual/en/language.pseudo-types.php#language.types.callback 'callback'}
  14   * type are valid.
  15   *
  16   * Also see the {@link http://codex.wordpress.org/Plugin_API Plugin API} for
  17   * more information and examples on how to use a lot of these functions.
  18   *
  19   * @package WordPress
  20   * @subpackage Plugin
  21   * @since 1.5
  22   */
  23  
  24  /**
  25   * Hooks a function or method to a specific filter action.
  26   *
  27   * Filters are the hooks that WordPress launches to modify text of various types
  28   * before adding it to the database or sending it to the browser screen. Plugins
  29   * can specify that one or more of its PHP functions is executed to
  30   * modify specific types of text at these times, using the Filter API.
  31   *
  32   * To use the API, the following code should be used to bind a callback to the
  33   * filter.
  34   *
  35   * <code>
  36   * function example_hook($example) { echo $example; }
  37   * add_filter('example_filter', 'example_hook');
  38   * </code>
  39   *
  40   * In WordPress 1.5.1+, hooked functions can take extra arguments that are set
  41   * when the matching do_action() or apply_filters() call is run. The
  42   * $accepted_args allow for calling functions only when the number of args
  43   * match. Hooked functions can take extra arguments that are set when the
  44   * matching do_action() or apply_filters() call is run. For example, the action
  45   * comment_id_not_found will pass any functions that hook onto it the ID of the
  46   * requested comment.
  47   *
  48   * <strong>Note:</strong> the function will return true no matter if the
  49   * function was hooked fails or not. There are no checks for whether the
  50   * function exists beforehand and no checks to whether the <tt>$function_to_add
  51   * is even a string. It is up to you to take care and this is done for
  52   * optimization purposes, so everything is as quick as possible.
  53   *
  54   * @package WordPress
  55   * @subpackage Plugin
  56   * @since 0.71
  57   * @global array $wp_filter Stores all of the filters added in the form of
  58   *    wp_filter['tag']['array of priorities']['array of functions serialized']['array of ['array (functions, accepted_args)']']
  59   * @global array $merged_filters Tracks the tags that need to be merged for later. If the hook is added, it doesn't need to run through that process.
  60   *
  61   * @param string $tag The name of the filter to hook the $function_to_add to.
  62   * @param callback $function_to_add The name of the function to be called when the filter is applied.
  63   * @param int $priority optional. Used to specify the order in which the functions associated with a particular action are executed (default: 10). Lower numbers correspond with earlier execution, and functions with the same priority are executed in the order in which they were added to the action.
  64   * @param int $accepted_args optional. The number of arguments the function accept (default 1).
  65   * @return boolean true
  66   */
  67  function add_filter($tag, $function_to_add, $priority = 10, $accepted_args = 1) {
  68      global $wp_filter, $merged_filters;
  69  
  70      $idx = _wp_filter_build_unique_id($tag, $function_to_add, $priority);
  71      $wp_filter[$tag][$priority][$idx] = array('function' => $function_to_add, 'accepted_args' => $accepted_args);
  72      unset( $merged_filters[ $tag ] );
  73      return true;
  74  }
  75  
  76  /**
  77   * Check if any filter has been registered for a hook.
  78   *
  79   * @package WordPress
  80   * @subpackage Plugin
  81   * @since 2.5
  82   * @global array $wp_filter Stores all of the filters
  83   *
  84   * @param string $tag The name of the filter hook.
  85   * @param callback $function_to_check optional.  If specified, return the priority of that function on this hook or false if not attached.
  86   * @return int|boolean Optionally returns the priority on that hook for the specified function.
  87   */
  88  function has_filter($tag, $function_to_check = false) {
  89      global $wp_filter;
  90  
  91      $has = !empty($wp_filter[$tag]);
  92      if ( false === $function_to_check || false == $has )
  93          return $has;
  94  
  95      if ( !$idx = _wp_filter_build_unique_id($tag, $function_to_check, false) )
  96          return false;
  97  
  98      foreach ( (array) array_keys($wp_filter[$tag]) as $priority ) {
  99          if ( isset($wp_filter[$tag][$priority][$idx]) )
 100              return $priority;
 101      }
 102  
 103      return false;
 104  }
 105  
 106  /**
 107   * Call the functions added to a filter hook.
 108   *
 109   * The callback functions attached to filter hook $tag are invoked by calling
 110   * this function. This function can be used to create a new filter hook by
 111   * simply calling this function with the name of the new hook specified using
 112   * the $tag parameter.
 113   *
 114   * The function allows for additional arguments to be added and passed to hooks.
 115   * <code>
 116   * function example_hook($string, $arg1, $arg2)
 117   * {
 118   *        //Do stuff
 119   *        return $string;
 120   * }
 121   * $value = apply_filters('example_filter', 'filter me', 'arg1', 'arg2');
 122   * </code>
 123   *
 124   * @package WordPress
 125   * @subpackage Plugin
 126   * @since 0.71
 127   * @global array $wp_filter Stores all of the filters
 128   * @global array $merged_filters Merges the filter hooks using this function.
 129   * @global array $wp_current_filter stores the list of current filters with the current one last
 130   *
 131   * @param string $tag The name of the filter hook.
 132   * @param mixed $value The value on which the filters hooked to <tt>$tag</tt> are applied on.
 133   * @param mixed $var,... Additional variables passed to the functions hooked to <tt>$tag</tt>.
 134   * @return mixed The filtered value after all hooked functions are applied to it.
 135   */
 136  function apply_filters($tag, $value) {
 137      global $wp_filter, $merged_filters, $wp_current_filter;
 138  
 139      $args = array();
 140      $wp_current_filter[] = $tag;
 141  
 142      // Do 'all' actions first
 143      if ( isset($wp_filter['all']) ) {
 144          $args = func_get_args();
 145          _wp_call_all_hook($args);
 146      }
 147  
 148      if ( !isset($wp_filter[$tag]) ) {
 149          array_pop($wp_current_filter);
 150          return $value;
 151      }
 152  
 153      // Sort
 154      if ( !isset( $merged_filters[ $tag ] ) ) {
 155          ksort($wp_filter[$tag]);
 156          $merged_filters[ $tag ] = true;
 157      }
 158  
 159      reset( $wp_filter[ $tag ] );
 160  
 161      if ( empty($args) )
 162          $args = func_get_args();
 163  
 164      do {
 165          foreach( (array) current($wp_filter[$tag]) as $the_ )
 166              if ( !is_null($the_['function']) ){
 167                  $args[1] = $value;
 168                  $value = call_user_func_array($the_['function'], array_slice($args, 1, (int) $the_['accepted_args']));
 169              }
 170  
 171      } while ( next($wp_filter[$tag]) !== false );
 172  
 173      array_pop( $wp_current_filter );
 174  
 175      return $value;
 176  }
 177  
 178  /**
 179   * Execute functions hooked on a specific filter hook, specifying arguments in an array.
 180   *
 181   * @see apply_filters() This function is identical, but the arguments passed to the
 182   * functions hooked to <tt>$tag</tt> are supplied using an array.
 183   *
 184   * @package WordPress
 185   * @subpackage Plugin
 186   * @since 3.0.0
 187   * @global array $wp_filter Stores all of the filters
 188   * @global array $merged_filters Merges the filter hooks using this function.
 189   * @global array $wp_current_filter stores the list of current filters with the current one last
 190   *
 191   * @param string $tag The name of the filter hook.
 192   * @param array $args The arguments supplied to the functions hooked to <tt>$tag</tt>
 193   * @return mixed The filtered value after all hooked functions are applied to it.
 194   */
 195  function apply_filters_ref_array($tag, $args) {
 196      global $wp_filter, $merged_filters, $wp_current_filter;
 197  
 198      $wp_current_filter[] = $tag;
 199  
 200      // Do 'all' actions first
 201      if ( isset($wp_filter['all']) ) {
 202          $all_args = func_get_args();
 203          _wp_call_all_hook($all_args);
 204      }
 205  
 206      if ( !isset($wp_filter[$tag]) ) {
 207          array_pop($wp_current_filter);
 208          return $args[0];
 209      }
 210  
 211      // Sort
 212      if ( !isset( $merged_filters[ $tag ] ) ) {
 213          ksort($wp_filter[$tag]);
 214          $merged_filters[ $tag ] = true;
 215      }
 216  
 217      reset( $wp_filter[ $tag ] );
 218  
 219      do {
 220          foreach( (array) current($wp_filter[$tag]) as $the_ )
 221              if ( !is_null($the_['function']) )
 222                  $args[0] = call_user_func_array($the_['function'], array_slice($args, 0, (int) $the_['accepted_args']));
 223  
 224      } while ( next($wp_filter[$tag]) !== false );
 225  
 226      array_pop( $wp_current_filter );
 227  
 228      return $args[0];
 229  }
 230  
 231  /**
 232   * Removes a function from a specified filter hook.
 233   *
 234   * This function removes a function attached to a specified filter hook. This
 235   * method can be used to remove default functions attached to a specific filter
 236   * hook and possibly replace them with a substitute.
 237   *
 238   * To remove a hook, the $function_to_remove and $priority arguments must match
 239   * when the hook was added. This goes for both filters and actions. No warning
 240   * will be given on removal failure.
 241   *
 242   * @package WordPress
 243   * @subpackage Plugin
 244   * @since 1.2
 245   *
 246   * @param string $tag The filter hook to which the function to be removed is hooked.
 247   * @param callback $function_to_remove The name of the function which should be removed.
 248   * @param int $priority optional. The priority of the function (default: 10).
 249   * @param int $accepted_args optional. The number of arguments the function accpets (default: 1).
 250   * @return boolean Whether the function existed before it was removed.
 251   */
 252  function remove_filter($tag, $function_to_remove, $priority = 10, $accepted_args = 1) {
 253      $function_to_remove = _wp_filter_build_unique_id($tag, $function_to_remove, $priority);
 254  
 255      $r = isset($GLOBALS['wp_filter'][$tag][$priority][$function_to_remove]);
 256  
 257      if ( true === $r) {
 258          unset($GLOBALS['wp_filter'][$tag][$priority][$function_to_remove]);
 259          if ( empty($GLOBALS['wp_filter'][$tag][$priority]) )
 260              unset($GLOBALS['wp_filter'][$tag][$priority]);
 261          unset($GLOBALS['merged_filters'][$tag]);
 262      }
 263  
 264      return $r;
 265  }
 266  
 267  /**
 268   * Remove all of the hooks from a filter.
 269   *
 270   * @since 2.7
 271   *
 272   * @param string $tag The filter to remove hooks from.
 273   * @param int $priority The priority number to remove.
 274   * @return bool True when finished.
 275   */
 276  function remove_all_filters($tag, $priority = false) {
 277      global $wp_filter, $merged_filters;
 278  
 279      if( isset($wp_filter[$tag]) ) {
 280          if( false !== $priority && isset($wp_filter[$tag][$priority]) )
 281              unset($wp_filter[$tag][$priority]);
 282          else
 283              unset($wp_filter[$tag]);
 284      }
 285  
 286      if( isset($merged_filters[$tag]) )
 287          unset($merged_filters[$tag]);
 288  
 289      return true;
 290  }
 291  
 292  /**
 293   * Retrieve the name of the current filter or action.
 294   *
 295   * @package WordPress
 296   * @subpackage Plugin
 297   * @since 2.5
 298   *
 299   * @return string Hook name of the current filter or action.
 300   */
 301  function current_filter() {
 302      global $wp_current_filter;
 303      return end( $wp_current_filter );
 304  }
 305  
 306  
 307  /**
 308   * Hooks a function on to a specific action.
 309   *
 310   * Actions are the hooks that the WordPress core launches at specific points
 311   * during execution, or when specific events occur. Plugins can specify that
 312   * one or more of its PHP functions are executed at these points, using the
 313   * Action API.
 314   *
 315   * @uses add_filter() Adds an action. Parameter list and functionality are the same.
 316   *
 317   * @package WordPress
 318   * @subpackage Plugin
 319   * @since 1.2
 320   *
 321   * @param string $tag The name of the action to which the $function_to_add is hooked.
 322   * @param callback $function_to_add The name of the function you wish to be called.
 323   * @param int $priority optional. Used to specify the order in which the functions associated with a particular action are executed (default: 10). Lower numbers correspond with earlier execution, and functions with the same priority are executed in the order in which they were added to the action.
 324   * @param int $accepted_args optional. The number of arguments the function accept (default 1).
 325   */
 326  function add_action($tag, $function_to_add, $priority = 10, $accepted_args = 1) {
 327      return add_filter($tag, $function_to_add, $priority, $accepted_args);
 328  }
 329  
 330  
 331  /**
 332   * Execute functions hooked on a specific action hook.
 333   *
 334   * This function invokes all functions attached to action hook $tag. It is
 335   * possible to create new action hooks by simply calling this function,
 336   * specifying the name of the new hook using the <tt>$tag</tt> parameter.
 337   *
 338   * You can pass extra arguments to the hooks, much like you can with
 339   * apply_filters().
 340   *
 341   * @see apply_filters() This function works similar with the exception that
 342   * nothing is returned and only the functions or methods are called.
 343   *
 344   * @package WordPress
 345   * @subpackage Plugin
 346   * @since 1.2
 347   * @global array $wp_filter Stores all of the filters
 348   * @global array $wp_actions Increments the amount of times action was triggered.
 349   *
 350   * @param string $tag The name of the action to be executed.
 351   * @param mixed $arg,... Optional additional arguments which are passed on to the functions hooked to the action.
 352   * @return null Will return null if $tag does not exist in $wp_filter array
 353   */
 354  function do_action($tag, $arg = '') {
 355      global $wp_filter, $wp_actions, $merged_filters, $wp_current_filter;
 356  
 357      if ( ! isset($wp_actions) )
 358          $wp_actions = array();
 359  
 360      if ( ! isset($wp_actions[$tag]) )
 361          $wp_actions[$tag] = 1;
 362      else
 363          ++$wp_actions[$tag];
 364  
 365      $wp_current_filter[] = $tag;
 366  
 367      // Do 'all' actions first
 368      if ( isset($wp_filter['all']) ) {
 369          $all_args = func_get_args();
 370          _wp_call_all_hook($all_args);
 371      }
 372  
 373      if ( !isset($wp_filter[$tag]) ) {
 374          array_pop($wp_current_filter);
 375          return;
 376      }
 377  
 378      $args = array();
 379      if ( is_array($arg) && 1 == count($arg) && isset($arg[0]) && is_object($arg[0]) ) // array(&$this)
 380          $args[] =& $arg[0];
 381      else
 382          $args[] = $arg;
 383      for ( $a = 2; $a < func_num_args(); $a++ )
 384          $args[] = func_get_arg($a);
 385  
 386      // Sort
 387      if ( !isset( $merged_filters[ $tag ] ) ) {
 388          ksort($wp_filter[$tag]);
 389          $merged_filters[ $tag ] = true;
 390      }
 391  
 392      reset( $wp_filter[ $tag ] );
 393  
 394      do {
 395          foreach ( (array) current($wp_filter[$tag]) as $the_ )
 396              if ( !is_null($the_['function']) )
 397                  call_user_func_array($the_['function'], array_slice($args, 0, (int) $the_['accepted_args']));
 398  
 399      } while ( next($wp_filter[$tag]) !== false );
 400  
 401      array_pop($wp_current_filter);
 402  }
 403  
 404  /**
 405   * Retrieve the number times an action is fired.
 406   *
 407   * @package WordPress
 408   * @subpackage Plugin
 409   * @since 2.1
 410   * @global array $wp_actions Increments the amount of times action was triggered.
 411   *
 412   * @param string $tag The name of the action hook.
 413   * @return int The number of times action hook <tt>$tag</tt> is fired
 414   */
 415  function did_action($tag) {
 416      global $wp_actions;
 417  
 418      if ( ! isset( $wp_actions ) || ! isset( $wp_actions[$tag] ) )
 419          return 0;
 420  
 421      return $wp_actions[$tag];
 422  }
 423  
 424  /**
 425   * Execute functions hooked on a specific action hook, specifying arguments in an array.
 426   *
 427   * @see do_action() This function is identical, but the arguments passed to the
 428   * functions hooked to <tt>$tag</tt> are supplied using an array.
 429   *
 430   * @package WordPress
 431   * @subpackage Plugin
 432   * @since 2.1
 433   * @global array $wp_filter Stores all of the filters
 434   * @global array $wp_actions Increments the amount of times action was triggered.
 435   *
 436   * @param string $tag The name of the action to be executed.
 437   * @param array $args The arguments supplied to the functions hooked to <tt>$tag</tt>
 438   * @return null Will return null if $tag does not exist in $wp_filter array
 439   */
 440  function do_action_ref_array($tag, $args) {
 441      global $wp_filter, $wp_actions, $merged_filters, $wp_current_filter;
 442  
 443      if ( ! isset($wp_actions) )
 444          $wp_actions = array();
 445  
 446      if ( ! isset($wp_actions[$tag]) )
 447          $wp_actions[$tag] = 1;
 448      else
 449          ++$wp_actions[$tag];
 450  
 451      $wp_current_filter[] = $tag;
 452  
 453      // Do 'all' actions first
 454      if ( isset($wp_filter['all']) ) {
 455          $all_args = func_get_args();
 456          _wp_call_all_hook($all_args);
 457      }
 458  
 459      if ( !isset($wp_filter[$tag]) ) {
 460          array_pop($wp_current_filter);
 461          return;
 462      }
 463  
 464      // Sort
 465      if ( !isset( $merged_filters[ $tag ] ) ) {
 466          ksort($wp_filter[$tag]);
 467          $merged_filters[ $tag ] = true;
 468      }
 469  
 470      reset( $wp_filter[ $tag ] );
 471  
 472      do {
 473          foreach( (array) current($wp_filter[$tag]) as $the_ )
 474              if ( !is_null($the_['function']) )
 475                  call_user_func_array($the_['function'], array_slice($args, 0, (int) $the_['accepted_args']));
 476  
 477      } while ( next($wp_filter[$tag]) !== false );
 478  
 479      array_pop($wp_current_filter);
 480  }
 481  
 482  /**
 483   * Check if any action has been registered for a hook.
 484   *
 485   * @package WordPress
 486   * @subpackage Plugin
 487   * @since 2.5
 488   * @see has_filter() has_action() is an alias of has_filter().
 489   *
 490   * @param string $tag The name of the action hook.
 491   * @param callback $function_to_check optional.  If specified, return the priority of that function on this hook or false if not attached.
 492   * @return int|boolean Optionally returns the priority on that hook for the specified function.
 493   */
 494  function has_action($tag, $function_to_check = false) {
 495      return has_filter($tag, $function_to_check);
 496  }
 497  
 498  /**
 499   * Removes a function from a specified action hook.
 500   *
 501   * This function removes a function attached to a specified action hook. This
 502   * method can be used to remove default functions attached to a specific filter
 503   * hook and possibly replace them with a substitute.
 504   *
 505   * @package WordPress
 506   * @subpackage Plugin
 507   * @since 1.2
 508   *
 509   * @param string $tag The action hook to which the function to be removed is hooked.
 510   * @param callback $function_to_remove The name of the function which should be removed.
 511   * @param int $priority optional The priority of the function (default: 10).
 512   * @param int $accepted_args optional. The number of arguments the function accpets (default: 1).
 513   * @return boolean Whether the function is removed.
 514   */
 515  function remove_action($tag, $function_to_remove, $priority = 10, $accepted_args = 1) {
 516      return remove_filter($tag, $function_to_remove, $priority, $accepted_args);
 517  }
 518  
 519  /**
 520   * Remove all of the hooks from an action.
 521   *
 522   * @since 2.7
 523   *
 524   * @param string $tag The action to remove hooks from.
 525   * @param int $priority The priority number to remove them from.
 526   * @return bool True when finished.
 527   */
 528  function remove_all_actions($tag, $priority = false) {
 529      return remove_all_filters($tag, $priority);
 530  }
 531  
 532  //
 533  // Functions for handling plugins.
 534  //
 535  
 536  /**
 537   * Gets the basename of a plugin.
 538   *
 539   * This method extracts the name of a plugin from its filename.
 540   *
 541   * @package WordPress
 542   * @subpackage Plugin
 543   * @since 1.5
 544   *
 545   * @access private
 546   *
 547   * @param string $file The filename of plugin.
 548   * @return string The name of a plugin.
 549   * @uses WP_PLUGIN_DIR
 550   */
 551  function plugin_basename($file) {
 552      $file = str_replace('\\','/',$file); // sanitize for Win32 installs
 553      $file = preg_replace('|/+|','/', $file); // remove any duplicate slash
 554      $plugin_dir = str_replace('\\','/',WP_PLUGIN_DIR); // sanitize for Win32 installs
 555      $plugin_dir = preg_replace('|/+|','/', $plugin_dir); // remove any duplicate slash
 556      $mu_plugin_dir = str_replace('\\','/',WPMU_PLUGIN_DIR); // sanitize for Win32 installs
 557      $mu_plugin_dir = preg_replace('|/+|','/', $mu_plugin_dir); // remove any duplicate slash
 558      $file = preg_replace('#^' . preg_quote($plugin_dir, '#') . '/|^' . preg_quote($mu_plugin_dir, '#') . '/#','',$file); // get relative path from plugins dir
 559      $file = trim($file, '/');
 560      return $file;
 561  }
 562  
 563  /**
 564   * Gets the filesystem directory path (with trailing slash) for the plugin __FILE__ passed in
 565   * @package WordPress
 566   * @subpackage Plugin
 567   * @since 2.8
 568   *
 569   * @param string $file The filename of the plugin (__FILE__)
 570   * @return string the filesystem path of the directory that contains the plugin
 571   */
 572  function plugin_dir_path( $file ) {
 573      return trailingslashit( dirname( $file ) );
 574  }
 575  
 576  /**
 577   * Gets the URL directory path (with trailing slash) for the plugin __FILE__ passed in
 578   * @package WordPress
 579   * @subpackage Plugin
 580   * @since 2.8
 581   *
 582   * @param string $file The filename of the plugin (__FILE__)
 583   * @return string the URL path of the directory that contains the plugin
 584   */
 585  function plugin_dir_url( $file ) {
 586      return trailingslashit( plugins_url( '', $file ) );
 587  }
 588  
 589  /**
 590   * Set the activation hook for a plugin.
 591   *
 592   * When a plugin is activated, the action 'activate_PLUGINNAME' hook is
 593   * activated. In the name of this hook, PLUGINNAME is replaced with the name of
 594   * the plugin, including the optional subdirectory. For example, when the plugin
 595   * is located in wp-content/plugin/sampleplugin/sample.php, then the name of
 596   * this hook will become 'activate_sampleplugin/sample.php'. When the plugin
 597   * consists of only one file and is (as by default) located at
 598   * wp-content/plugin/sample.php the name of this hook will be
 599   * 'activate_sample.php'.
 600   *
 601   * @package WordPress
 602   * @subpackage Plugin
 603   * @since 2.0
 604   *
 605   * @param string $file The filename of the plugin including the path.
 606   * @param callback $function the function hooked to the 'activate_PLUGIN' action.
 607   */
 608  function register_activation_hook($file, $function) {
 609      $file = plugin_basename($file);
 610      add_action('activate_' . $file, $function);
 611  }
 612  
 613  /**
 614   * Set the deactivation hook for a plugin.
 615   *
 616   * When a plugin is deactivated, the action 'deactivate_PLUGINNAME' hook is
 617   * deactivated. In the name of this hook, PLUGINNAME is replaced with the name
 618   * of the plugin, including the optional subdirectory. For example, when the
 619   * plugin is located in wp-content/plugin/sampleplugin/sample.php, then
 620   * the name of this hook will become 'activate_sampleplugin/sample.php'.
 621   *
 622   * When the plugin consists of only one file and is (as by default) located at
 623   * wp-content/plugin/sample.php the name of this hook will be
 624   * 'activate_sample.php'.
 625   *
 626   * @package WordPress
 627   * @subpackage Plugin
 628   * @since 2.0
 629   *
 630   * @param string $file The filename of the plugin including the path.
 631   * @param callback $function the function hooked to the 'activate_PLUGIN' action.
 632   */
 633  function register_deactivation_hook($file, $function) {
 634      $file = plugin_basename($file);
 635      add_action('deactivate_' . $file, $function);
 636  }
 637  
 638  /**
 639   * Set the uninstallation hook for a plugin.
 640   *
 641   * Registers the uninstall hook that will be called when the user clicks on the
 642   * uninstall link that calls for the plugin to uninstall itself. The link won't
 643   * be active unless the plugin hooks into the action.
 644   *
 645   * The plugin should not run arbitrary code outside of functions, when
 646   * registering the uninstall hook. In order to run using the hook, the plugin
 647   * will have to be included, which means that any code laying outside of a
 648   * function will be run during the uninstall process. The plugin should not
 649   * hinder the uninstall process.
 650   *
 651   * If the plugin can not be written without running code within the plugin, then
 652   * the plugin should create a file named 'uninstall.php' in the base plugin
 653   * folder. This file will be called, if it exists, during the uninstall process
 654   * bypassing the uninstall hook. The plugin, when using the 'uninstall.php'
 655   * should always check for the 'WP_UNINSTALL_PLUGIN' constant, before
 656   * executing.
 657   *
 658   * @since 2.7
 659   *
 660   * @param string $file
 661   * @param callback $callback The callback to run when the hook is called.
 662   */
 663  function register_uninstall_hook($file, $callback) {
 664      // The option should not be autoloaded, because it is not needed in most
 665      // cases. Emphasis should be put on using the 'uninstall.php' way of
 666      // uninstalling the plugin.
 667      $uninstallable_plugins = (array) backpress_get_option('uninstall_plugins');
 668      $uninstallable_plugins[plugin_basename($file)] = $callback;
 669      backpress_update_option('uninstall_plugins', $uninstallable_plugins);
 670  }
 671  
 672  /**
 673   * Calls the 'all' hook, which will process the functions hooked into it.
 674   *
 675   * The 'all' hook passes all of the arguments or parameters that were used for
 676   * the hook, which this function was called for.
 677   *
 678   * This function is used internally for apply_filters(), do_action(), and
 679   * do_action_ref_array() and is not meant to be used from outside those
 680   * functions. This function does not check for the existence of the all hook, so
 681   * it will fail unless the all hook exists prior to this function call.
 682   *
 683   * @package WordPress
 684   * @subpackage Plugin
 685   * @since 2.5
 686   * @access private
 687   *
 688   * @uses $wp_filter Used to process all of the functions in the 'all' hook
 689   *
 690   * @param array $args The collected parameters from the hook that was called.
 691   * @param string $hook Optional. The hook name that was used to call the 'all' hook.
 692   */
 693  function _wp_call_all_hook($args) {
 694      global $wp_filter;
 695  
 696      reset( $wp_filter['all'] );
 697      do {
 698          foreach( (array) current($wp_filter['all']) as $the_ )
 699              if ( !is_null($the_['function']) )
 700                  call_user_func_array($the_['function'], $args);
 701  
 702      } while ( next($wp_filter['all']) !== false );
 703  }
 704  
 705  /**
 706   * Build Unique ID for storage and retrieval.
 707   *
 708   * The old way to serialize the callback caused issues and this function is the
 709   * solution. It works by checking for objects and creating an a new property in
 710   * the class to keep track of the object and new objects of the same class that
 711   * need to be added.
 712   *
 713   * It also allows for the removal of actions and filters for objects after they
 714   * change class properties. It is possible to include the property $wp_filter_id
 715   * in your class and set it to "null" or a number to bypass the workaround.
 716   * However this will prevent you from adding new classes and any new classes
 717   * will overwrite the previous hook by the same class.
 718   *
 719   * Functions and static method callbacks are just returned as strings and
 720   * shouldn't have any speed penalty.
 721   *
 722   * @package WordPress
 723   * @subpackage Plugin
 724   * @access private
 725   * @since 2.2.3
 726   * @link http://trac.wordpress.org/ticket/3875
 727   *
 728   * @global array $wp_filter Storage for all of the filters and actions
 729   * @param string $tag Used in counting how many hooks were applied
 730   * @param callback $function Used for creating unique id
 731   * @param int|bool $priority Used in counting how many hooks were applied.  If === false and $function is an object reference, we return the unique id only if it already has one, false otherwise.
 732   * @param string $type filter or action
 733   * @return string|bool Unique ID for usage as array key or false if $priority === false and $function is an object reference, and it does not already have a uniqe id.
 734   */
 735  function _wp_filter_build_unique_id($tag, $function, $priority) {
 736      global $wp_filter;
 737      static $filter_id_count = 0;
 738  
 739      if ( is_string($function) )
 740          return $function;
 741  
 742      if ( is_object($function) ) {
 743          // Closures are currently implemented as objects
 744          $function = array( $function, '' );
 745      } else {
 746          $function = (array) $function;
 747      }
 748  
 749      if (is_object($function[0]) ) {
 750          // Object Class Calling
 751          if ( function_exists('spl_object_hash') ) {
 752              return spl_object_hash($function[0]) . $function[1];
 753          } else {
 754              $obj_idx = get_class($function[0]).$function[1];
 755              if ( !isset($function[0]->wp_filter_id) ) {
 756                  if ( false === $priority )
 757                      return false;
 758                  $obj_idx .= isset($wp_filter[$tag][$priority]) ? count((array)$wp_filter[$tag][$priority]) : $filter_id_count;
 759                  $function[0]->wp_filter_id = $filter_id_count;
 760                  ++$filter_id_count;
 761              } else {
 762                  $obj_idx .= $function[0]->wp_filter_id;
 763              }
 764  
 765              return $obj_idx;
 766          }
 767      } else if ( is_string($function[0]) ) {
 768          // Static Calling
 769          return $function[0].$function[1];
 770      }
 771  }


Generated: Wed Dec 19 01:01:51 2018 Cross-referenced by PHPXref 0.7.1