enmi-conf.org: comparison wp/wp-includes/plugin.php

equal deleted inserted replaced

-:3d4e9c994f10
+:a86126ab1dd4
 *
 * The API callback examples reference functions, but can be methods of classes.
 * To hook methods, you'll need to pass an array one of two ways.
 *
 * Any of the syntaxes explained in the PHP documentation for the
-* {@link https://secure.php.net/manual/en/language.pseudo-types.php#language.types.callback 'callback'}
+* {@link https://www.php.net/manual/en/language.pseudo-types.php#language.types.callback 'callback'}
 * type are valid.
 *
-* Also see the {@link https://codex.wordpress.org/Plugin_API Plugin API} for
+* Also see the {@link https://developer.wordpress.org/plugins/ Plugin API} for
 * more information and examples on how to use a lot of these functions.
 *
 * This file should have no external dependencies.
 *
 * @package WordPress
 * @subpackage Plugin
 * @since 1.5.0
 */
 // Initialize the filter globals.
-require( dirname( __FILE__ ) . '/class-wp-hook.php' );
+require __DIR__ . '/class-wp-hook.php';
 /** @var WP_Hook[] $wp_filter */
 global $wp_filter, $wp_actions, $wp_current_filter;
 if ( $wp_filter ) {
 * It is up to you to take care. This is done for optimization purposes, so
 * everything is as quick as possible.
 *
 * @since 0.71
 *
-* @global array $wp_filter      A multidimensional array of all hooks and the callbacks hooked to them.
+* @global array $wp_filter A multidimensional array of all hooks and the callbacks hooked to them.
 *
 * @param string   $tag             The name of the filter to hook the $function_to_add callback to.
 * @param callable $function_to_add The callback to be run when the filter is applied.
 * @param int      $priority        Optional. Used to specify the order in which the functions
-*                                  associated with a particular action are executed. Default 10.
+*                                  associated with a particular action are executed.
 *                                  Lower numbers correspond with earlier execution,
 *                                  and functions with the same priority are executed
-*                                  in the order in which they were added to the action.
+*                                  in the order in which they were added to the action. Default 10.
 * @param int      $accepted_args   Optional. The number of arguments the function accepts. Default 1.
 * @return true
 */
 function add_filter( $tag, $function_to_add, $priority = 10, $accepted_args = 1 ) {
 	global $wp_filter;
 /**
 * Check if any filter has been registered for a hook.
 *
 * @since 2.5.0
 *
-* @global array $wp_filter Stores all of the filters.
+* @global array $wp_filter Stores all of the filters and actions.
 *
 * @param string        $tag               The name of the filter hook.
 * @param callable|bool $function_to_check Optional. The callback to check for. Default false.
 * @return false|int If $function_to_check is omitted, returns boolean for whether the hook has
 *                   anything registered. When checking a specific function, the priority of that
 	return $wp_filter[ $tag ]->has_filter( $tag, $function_to_check );
 }
 /**
-* Call the functions added to a filter hook.
+* Calls the callback functions that have been added to a filter hook.
 *
-* The callback functions attached to filter hook $tag are invoked by calling
+* The callback functions attached to the filter hook are invoked by calling
 * this function. This function can be used to create a new filter hook by
 * simply calling this function with the name of the new hook specified using
-* the $tag parameter.
+* the `$tag` parameter.
 *
-* The function allows for additional arguments to be added and passed to hooks.
+* The function also allows for multiple additional arguments to be passed to hooks.
 *
-*     // Our filter callback function
+* Example usage:
+*
+*     // The filter callback function.
 *     function example_callback( $string, $arg1, $arg2 ) {
-*         // (maybe) modify $string
+*         // (maybe) modify $string.
 *         return $string;
 *     }
 *     add_filter( 'example_filter', 'example_callback', 10, 3 );
 *
 *     /*
-*      * Apply the filters by calling the 'example_callback' function we
+*      * Apply the filters by calling the 'example_callback()' function
-*      * "hooked" to 'example_filter' using the add_filter() function above.
+*      * that's hooked onto `example_filter` above.
-*      * - 'example_filter' is the filter hook $tag
+*      *
-*      * - 'filter me' is the value being filtered
+*      * - 'example_filter' is the filter hook.
+*      * - 'filter me' is the value being filtered.
 *      * - $arg1 and $arg2 are the additional arguments passed to the callback.
 *     $value = apply_filters( 'example_filter', 'filter me', $arg1, $arg2 );
 *
 * @since 0.71
 *
-* @global array $wp_filter         Stores all of the filters.
+* @global array $wp_filter         Stores all of the filters and actions.
 * @global array $wp_current_filter Stores the list of current filters with the current one last.
 *
 * @param string $tag     The name of the filter hook.
-* @param mixed  $value   The value on which the filters hooked to `$tag` are applied on.
+* @param mixed  $value   The value to filter.
-* @param mixed  $var,... Additional variables passed to the functions hooked to `$tag`.
+* @param mixed  ...$args Additional parameters to pass to the callback functions.
 * @return mixed The filtered value after all hooked functions are applied to it.
 */
 function apply_filters( $tag, $value ) {
 	global $wp_filter, $wp_current_filter;
-	$args = array();
+	$args = func_get_args();
 	// Do 'all' actions first.
 	if ( isset( $wp_filter['all'] ) ) {
 		$wp_current_filter[] = $tag;
-		$args                = func_get_args();
 		_wp_call_all_hook( $args );
 	}
 	if ( ! isset( $wp_filter[ $tag ] ) ) {
 		if ( isset( $wp_filter['all'] ) ) {
 	if ( ! isset( $wp_filter['all'] ) ) {
 		$wp_current_filter[] = $tag;
 	}
-	if ( empty( $args ) ) {
+	// Don't pass the tag name to WP_Hook.
-		$args = func_get_args();
-	}
-	// don't pass the tag name to WP_Hook
 	array_shift( $args );
 	$filtered = $wp_filter[ $tag ]->apply_filters( $value, $args );
 	array_pop( $wp_current_filter );
 	return $filtered;
 }
 /**
-* Execute functions hooked on a specific filter hook, specifying arguments in an array.
+* Calls the callback functions that have been added to a filter hook, specifying arguments in an array.
 *
 * @since 3.0.0
 *
 * @see apply_filters() This function is identical, but the arguments passed to the
 * functions hooked to `$tag` are supplied using an array.
 *
-* @global array $wp_filter         Stores all of the filters
+* @global array $wp_filter         Stores all of the filters and actions.
-* @global array $wp_current_filter Stores the list of current filters with the current one last
+* @global array $wp_current_filter Stores the list of current filters with the current one last.
 *
 * @param string $tag  The name of the filter hook.
 * @param array  $args The arguments supplied to the functions hooked to $tag.
 * @return mixed The filtered value after all hooked functions are applied to it.
 */
 function apply_filters_ref_array( $tag, $args ) {
 	global $wp_filter, $wp_current_filter;
-	// Do 'all' actions first
+	// Do 'all' actions first.
 	if ( isset( $wp_filter['all'] ) ) {
 		$wp_current_filter[] = $tag;
-		$all_args            = func_get_args();
+		$all_args            = func_get_args(); // phpcs:ignore PHPCompatibility.FunctionUse.ArgumentFunctionsReportCurrentValue.NeedsInspection
 		_wp_call_all_hook( $all_args );
 	}
 	if ( ! isset( $wp_filter[ $tag ] ) ) {
 		if ( isset( $wp_filter['all'] ) ) {
 * when the hook was added. This goes for both filters and actions. No warning
 * will be given on removal failure.
 *
 * @since 1.2.0
 *
-* @global array $wp_filter         Stores all of the filters
+* @global array $wp_filter Stores all of the filters and actions.
 *
 * @param string   $tag                The filter hook to which the function to be removed is hooked.
 * @param callable $function_to_remove The name of the function which should be removed.
 * @param int      $priority           Optional. The priority of the function. Default 10.
 * @return bool    Whether the function existed before it was removed.
 /**
 * Remove all of the hooks from a filter.
 *
 * @since 2.7.0
 *
-* @global array $wp_filter  Stores all of the filters
+* @global array $wp_filter Stores all of the filters and actions.
 *
 * @param string   $tag      The filter to remove hooks from.
 * @param int|bool $priority Optional. The priority number to remove. Default false.
 * @return true True when finished.
 */
 	if ( null === $filter ) {
 		return ! empty( $wp_current_filter );
 	}
-	return in_array( $filter, $wp_current_filter );
+	return in_array( $filter, $wp_current_filter, true );
 }
 /**
 * Retrieve the name of an action currently being processed.
 *
 *
 * This function invokes all functions attached to action hook `$tag`. It is
 * possible to create new action hooks by simply calling this function,
 * specifying the name of the new hook using the `$tag` parameter.
 *
-* You can pass extra arguments to the hooks, much like you can with apply_filters().
+* You can pass extra arguments to the hooks, much like you can with `apply_filters()`.
+*
+* Example usage:
+*
+*     // The action callback function.
+*     function example_callback( $arg1, $arg2 ) {
+*         // (maybe) do something with the args.
+*     }
+*     add_action( 'example_action', 'example_callback', 10, 2 );
+*
+*     /*
+*      * Trigger the actions by calling the 'example_callback()' function
+*      * that's hooked onto `example_action` above.
+*      *
+*      * - 'example_action' is the action hook.
+*      * - $arg1 and $arg2 are the additional arguments passed to the callback.
+*     $value = do_action( 'example_action', $arg1, $arg2 );
 *
 * @since 1.2.0
-*
+* @since 5.3.0 Formalized the existing and already documented `...$arg` parameter
-* @global array $wp_filter         Stores all of the filters
+*              by adding it to the function signature.
+*
+* @global array $wp_filter         Stores all of the filters and actions.
 * @global array $wp_actions        Increments the amount of times action was triggered.
-* @global array $wp_current_filter Stores the list of current filters with the current one last
+* @global array $wp_current_filter Stores the list of current filters with the current one last.
 *
-* @param string $tag     The name of the action to be executed.
+* @param string $tag    The name of the action to be executed.
-* @param mixed  $arg,... Optional. Additional arguments which are passed on to the
+* @param mixed  ...$arg Optional. Additional arguments which are passed on to the
-*                        functions hooked to the action. Default empty.
+*                       functions hooked to the action. Default empty.
 */
-function do_action( $tag, $arg = '' ) {
+function do_action( $tag, ...$arg ) {
 	global $wp_filter, $wp_actions, $wp_current_filter;
 	if ( ! isset( $wp_actions[ $tag ] ) ) {
 		$wp_actions[ $tag ] = 1;
 	} else {
 		++$wp_actions[ $tag ];
 	}
-	// Do 'all' actions first
+	// Do 'all' actions first.
 	if ( isset( $wp_filter['all'] ) ) {
 		$wp_current_filter[] = $tag;
-		$all_args            = func_get_args();
+		$all_args            = func_get_args(); // phpcs:ignore PHPCompatibility.FunctionUse.ArgumentFunctionsReportCurrentValue.NeedsInspection
 		_wp_call_all_hook( $all_args );
 	}
 	if ( ! isset( $wp_filter[ $tag ] ) ) {
 		if ( isset( $wp_filter['all'] ) ) {
 	if ( ! isset( $wp_filter['all'] ) ) {
 		$wp_current_filter[] = $tag;
 	}
-	$args = array();
+	if ( empty( $arg ) ) {
-	if ( is_array( $arg ) && 1 == count( $arg ) && isset( $arg[0] ) && is_object( $arg[0] ) ) { // array(&$this)
+		$arg[] = '';
-		$args[] =& $arg[0];
+	} elseif ( is_array( $arg[0] ) && 1 === count( $arg[0] ) && isset( $arg[0][0] ) && is_object( $arg[0][0] ) ) {
-	} else {
+		// Backward compatibility for PHP4-style passing of `array( &$this )` as action `$arg`.
-		$args[] = $arg;
+		$arg[0] = $arg[0][0];
 	}
-	for ( $a = 2, $num = func_num_args(); $a < $num; $a++ ) {
-		$args[] = func_get_arg( $a );
+	$wp_filter[ $tag ]->do_action( $arg );
-	}
-	$wp_filter[ $tag ]->do_action( $args );
 	array_pop( $wp_current_filter );
 }
 /**
 	return $wp_actions[ $tag ];
 }
 /**
-* Execute functions hooked on a specific action hook, specifying arguments in an array.
+* Calls the callback functions that have been added to an action hook, specifying arguments in an array.
 *
 * @since 2.1.0
 *
 * @see do_action() This function is identical, but the arguments passed to the
-*                  functions hooked to $tag< are supplied using an array.
+*                  functions hooked to `$tag` are supplied using an array.
-* @global array $wp_filter         Stores all of the filters
+* @global array $wp_filter         Stores all of the filters and actions.
 * @global array $wp_actions        Increments the amount of times action was triggered.
-* @global array $wp_current_filter Stores the list of current filters with the current one last
+* @global array $wp_current_filter Stores the list of current filters with the current one last.
 *
 * @param string $tag  The name of the action to be executed.
 * @param array  $args The arguments supplied to the functions hooked to `$tag`.
 */
 function do_action_ref_array( $tag, $args ) {
 		$wp_actions[ $tag ] = 1;
 	} else {
 		++$wp_actions[ $tag ];
 	}
-	// Do 'all' actions first
+	// Do 'all' actions first.
 	if ( isset( $wp_filter['all'] ) ) {
 		$wp_current_filter[] = $tag;
-		$all_args            = func_get_args();
+		$all_args            = func_get_args(); // phpcs:ignore PHPCompatibility.FunctionUse.ArgumentFunctionsReportCurrentValue.NeedsInspection
 		_wp_call_all_hook( $all_args );
 	}
 	if ( ! isset( $wp_filter[ $tag ] ) ) {
 		if ( isset( $wp_filter['all'] ) ) {
 *
 *     // Old filter.
 *     return apply_filters( 'wpdocs_filter', $value, $extra_arg );
 *
 *     // Deprecated.
-*     return apply_filters_deprecated( 'wpdocs_filter', array( $value, $extra_arg ), '4.9', 'wpdocs_new_filter' );
+*     return apply_filters_deprecated( 'wpdocs_filter', array( $value, $extra_arg ), '4.9.0', 'wpdocs_new_filter' );
 *
 * @since 4.6.0
 *
 * @see _deprecated_hook()
 *
 * @param string $tag         The name of the filter hook.
 * @param array  $args        Array of additional function arguments to be passed to apply_filters().
 * @param string $version     The version of WordPress that deprecated the hook.
-* @param string $replacement Optional. The hook that should have been used. Default false.
+* @param string $replacement Optional. The hook that should have been used. Default empty.
-* @param string $message     Optional. A message regarding the change. Default null.
+* @param string $message     Optional. A message regarding the change. Default empty.
 */
-function apply_filters_deprecated( $tag, $args, $version, $replacement = false, $message = null ) {
+function apply_filters_deprecated( $tag, $args, $version, $replacement = '', $message = '' ) {
 	if ( ! has_filter( $tag ) ) {
 		return $args[0];
 	}
 	_deprecated_hook( $tag, $version, $replacement, $message );
 * @see _deprecated_hook()
 *
 * @param string $tag         The name of the action hook.
 * @param array  $args        Array of additional function arguments to be passed to do_action().
 * @param string $version     The version of WordPress that deprecated the hook.
-* @param string $replacement Optional. The hook that should have been used.
+* @param string $replacement Optional. The hook that should have been used. Default empty.
-* @param string $message     Optional. A message regarding the change.
+* @param string $message     Optional. A message regarding the change. Default empty.
 */
-function do_action_deprecated( $tag, $args, $version, $replacement = false, $message = null ) {
+function do_action_deprecated( $tag, $args, $version, $replacement = '', $message = '' ) {
 	if ( ! has_action( $tag ) ) {
 		return;
 	}
 	_deprecated_hook( $tag, $version, $replacement, $message );
 	}
 	$plugin_dir    = wp_normalize_path( WP_PLUGIN_DIR );
 	$mu_plugin_dir = wp_normalize_path( WPMU_PLUGIN_DIR );
-	$file = preg_replace( '#^' . preg_quote( $plugin_dir, '#' ) . '/|^' . preg_quote( $mu_plugin_dir, '#' ) . '/#', '', $file ); // get relative path from plugins dir
+	// Get relative path from plugins directory.
+	$file = preg_replace( '#^' . preg_quote( $plugin_dir, '#' ) . '/|^' . preg_quote( $mu_plugin_dir, '#' ) . '/#', '', $file );
 	$file = trim( $file, '/' );
 	return $file;
 }
 /**
 *
 * @see wp_normalize_path()
 *
 * @global array $wp_plugin_paths
 *
-* @staticvar string $wp_plugin_path
-* @staticvar string $wpmu_plugin_path
-*
 * @param string $file Known path to the file.
 * @return bool Whether the path was able to be registered.
 */
 function wp_register_plugin_realpath( $file ) {
 	global $wp_plugin_paths;
-	// Normalize, but store as static to avoid recalculation of a constant value
+	// Normalize, but store as static to avoid recalculation of a constant value.
 	static $wp_plugin_path = null, $wpmu_plugin_path = null;
 	if ( ! isset( $wp_plugin_path ) ) {
 		$wp_plugin_path   = wp_normalize_path( WP_PLUGIN_DIR );
 		$wpmu_plugin_path = wp_normalize_path( WPMU_PLUGIN_DIR );
 	}
 	/*
 	 * The option should not be autoloaded, because it is not needed in most
 	 * cases. Emphasis should be put on using the 'uninstall.php' way of
 	 * uninstalling the plugin.
 	 */
-	$uninstallable_plugins                             = (array) get_option( 'uninstall_plugins' );
+	$uninstallable_plugins = (array) get_option( 'uninstall_plugins' );
-	$uninstallable_plugins[ plugin_basename( $file ) ] = $callback;
+	$plugin_basename       = plugin_basename( $file );
+	if ( ! isset( $uninstallable_plugins[ $plugin_basename ] ) || $uninstallable_plugins[ $plugin_basename ] !== $callback ) {
-	update_option( 'uninstall_plugins', $uninstallable_plugins );
+		$uninstallable_plugins[ $plugin_basename ] = $callback;
+		update_option( 'uninstall_plugins', $uninstallable_plugins );
+	}
 }
 /**
 * Call the 'all' hook, which will process the functions hooked into it.
 *
 * it will fail unless the all hook exists prior to this function call.
 *
 * @since 2.5.0
 * @access private
 *
-* @global array $wp_filter  Stores all of the filters
+* @global array $wp_filter Stores all of the filters and actions.
 *
 * @param array $args The collected parameters from the hook that was called.
 */
 function _wp_call_all_hook( $args ) {
 	global $wp_filter;
 * shouldn't have any speed penalty.
 *
 * @link https://core.trac.wordpress.org/ticket/3875
 *
 * @since 2.2.3
+* @since 5.3.0 Removed workarounds for spl_object_hash().
+*              `$tag` and `$priority` are no longer used,
+*              and the function always returns a string.
 * @access private
 *
-* @global array $wp_filter Storage for all of the filters and actions.
+* @param string   $tag      Unused. The name of the filter to build ID for.
-* @staticvar int $filter_id_count
+* @param callable $function The function to generate ID for.
-*
+* @param int      $priority Unused. The order in which the functions
-* @param string   $tag      Used in counting how many hooks were applied
+*                           associated with a particular action are executed.
-* @param callable $function Used for creating unique id
+* @return string Unique function ID for usage as array key.
-* @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.
-* @return string|false 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 unique id.
 */
 function _wp_filter_build_unique_id( $tag, $function, $priority ) {
-	global $wp_filter;
-	static $filter_id_count = 0;
 	if ( is_string( $function ) ) {
 		return $function;
 	}
 	if ( is_object( $function ) ) {
-		// Closures are currently implemented as objects
+		// Closures are currently implemented as objects.
 		$function = array( $function, '' );
 	} else {
 		$function = (array) $function;
 	}
 	if ( is_object( $function[0] ) ) {
-		// Object Class Calling
+		// Object class calling.
-		if ( function_exists( 'spl_object_hash' ) ) {
+		return spl_object_hash( $function[0] ) . $function[1];
-			return spl_object_hash( $function[0] ) . $function[1];
-		} else {
-			$obj_idx = get_class( $function[0] ) . $function[1];
-			if ( ! isset( $function[0]->wp_filter_id ) ) {
-				if ( false === $priority ) {
-					return false;
-				}
-				$obj_idx                  .= isset( $wp_filter[ $tag ][ $priority ] ) ? count( (array) $wp_filter[ $tag ][ $priority ] ) : $filter_id_count;
-				$function[0]->wp_filter_id = $filter_id_count;
-				++$filter_id_count;
-			} else {
-				$obj_idx .= $function[0]->wp_filter_id;
-			}
-			return $obj_idx;
-		}
 	} elseif ( is_string( $function[0] ) ) {
-		// Static Calling
+		// Static calling.
 		return $function[0] . '::' . $function[1];
 	}
 }

changeset 16	a86126ab1dd4
parent 9	177826044cd9
child 18	be944660c56a