| [ Index ] |
PHP Cross Reference of WordPress |
[Source view] [Print] [Project Stats]
The plugin API is located in this file, which allows for creating actions and filters and hooking functions, and methods. The functions or methods will then be run when the action or filter is called. 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.
| File Size: | 966 lines (34 kb) |
| Included or required: | 1 time |
| Referenced: | 0 times |
| Includes or requires: | 1 file wp-includes/class-wp-hook.php |
| add_filter( $hook_name, $callback, $priority = 10, $accepted_args = 1 ) X-Ref |
| Adds a callback function to a filter hook. WordPress offers filter hooks to allow plugins to modify various types of internal data at runtime. A plugin can modify data by binding a callback to a filter hook. When the filter is later applied, each bound callback is run in order of priority, and given the opportunity to modify a value by returning a new value. The following example shows how a callback function is bound to a filter hook. Note that `$example` is passed to the callback, (maybe) modified, then returned: function example_callback( $example ) { // Maybe modify $example in some way. return $example; } add_filter( 'example_filter', 'example_callback' ); Bound callbacks can accept from none to the total number of arguments passed as parameters in the corresponding apply_filters() call. In other words, if an apply_filters() call passes four total arguments, callbacks bound to it can accept none (the same as 1) of the arguments or up to four. The important part is that the `$accepted_args` value must reflect the number of arguments the bound callback *actually* opted to accept. If no arguments were accepted by the callback that is considered to be the same as accepting 1 argument. For example: // Filter call. $value = apply_filters( 'hook', $value, $arg2, $arg3 ); // Accepting zero/one arguments. function example_callback() { ... return 'some value'; } add_filter( 'hook', 'example_callback' ); // Where $priority is default 10, $accepted_args is default 1. // Accepting two arguments (three possible). function example_callback( $value, $arg2 ) { ... return $maybe_modified_value; } add_filter( 'hook', 'example_callback', 10, 2 ); // Where $priority is 10, $accepted_args is 2. *Note:* The function will return true whether or not the callback is valid. It is up to you to take care. This is done for optimization purposes, so everything is as quick as possible. return: true Always returns true. param: string $hook_name The name of the filter to add the callback to. param: callable $callback The callback to be run when the filter is applied. param: int $priority Optional. Used to specify the order in which the functions param: int $accepted_args Optional. The number of arguments the function accepts. Default 1. since: 0.71 |
| apply_filters( $hook_name, $value, ...$args ) X-Ref |
| Calls the callback functions that have been added to a filter hook. This function invokes all functions attached to filter hook `$hook_name`. It is possible to create new filter hooks by simply calling this function, specifying the name of the new hook using the `$hook_name` parameter. The function also allows for multiple additional arguments to be passed to hooks. Example usage: // The filter callback function. function example_callback( $string, $arg1, $arg2 ) { // (maybe) modify $string. return $string; } add_filter( 'example_filter', 'example_callback', 10, 3 ); /* * Apply the filters by calling the 'example_callback()' function * that's hooked onto `example_filter` above. * * - '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 ); return: mixed The filtered value after all hooked functions are applied to it. param: string $hook_name The name of the filter hook. param: mixed $value The value to filter. param: mixed ...$args Additional parameters to pass to the callback functions. since: 0.71 since: 6.0.0 Formalized the existing and already documented `...$args` parameter |
| apply_filters_ref_array( $hook_name, $args ) X-Ref |
| Calls the callback functions that have been added to a filter hook, specifying arguments in an array. return: mixed The filtered value after all hooked functions are applied to it. param: string $hook_name The name of the filter hook. param: array $args The arguments supplied to the functions hooked to `$hook_name`. since: 3.0.0 |
| has_filter( $hook_name, $callback = false ) X-Ref |
| Checks if any filter has been registered for a hook. When using the `$callback` argument, this function may return a non-boolean value that evaluates to false (e.g. 0), so use the `===` operator for testing the return value. return: bool|int If `$callback` is omitted, returns boolean for whether the hook has param: string $hook_name The name of the filter hook. param: callable|string|array|false $callback Optional. The callback to check for. since: 2.5.0 |
| remove_filter( $hook_name, $callback, $priority = 10 ) X-Ref |
| Removes a callback function from a filter hook. This can be used to remove default functions attached to a specific filter hook and possibly replace them with a substitute. To remove a hook, the `$callback` and `$priority` arguments must match when the hook was added. This goes for both filters and actions. No warning will be given on removal failure. return: bool Whether the function existed before it was removed. param: string $hook_name The filter hook to which the function to be removed is hooked. param: callable|string|array $callback The callback to be removed from running when the filter is applied. param: int $priority Optional. The exact priority used when adding the original since: 1.2.0 |
| remove_all_filters( $hook_name, $priority = false ) X-Ref |
| Removes all of the callback functions from a filter hook. return: true Always returns true. param: string $hook_name The filter to remove callbacks from. param: int|false $priority Optional. The priority number to remove them from. since: 2.7.0 |
| current_filter() X-Ref |
| Retrieves the name of the current filter hook. return: string Hook name of the current filter. since: 2.5.0 |
| doing_filter( $hook_name = null ) X-Ref |
| Returns whether or not a filter hook is currently being processed. The function current_filter() only returns the most recent filter or action being executed. did_action() returns true once the action is initially processed. This function allows detection for any filter currently being executed (regardless of whether it's the most recent filter to fire, in the case of hooks called from hook callbacks) to be verified. return: bool Whether the filter is currently in the stack. param: null|string $hook_name Optional. Filter hook to check. Defaults to null, since: 3.9.0 |
| add_action( $hook_name, $callback, $priority = 10, $accepted_args = 1 ) X-Ref |
| Adds a callback function to an action hook. Actions are the hooks that the WordPress core launches at specific points during execution, or when specific events occur. Plugins can specify that one or more of its PHP functions are executed at these points, using the Action API. return: true Always returns true. param: string $hook_name The name of the action to add the callback to. param: callable $callback The callback to be run when the action is called. param: int $priority Optional. Used to specify the order in which the functions param: int $accepted_args Optional. The number of arguments the function accepts. Default 1. since: 1.2.0 |
| do_action( $hook_name, ...$arg ) X-Ref |
| Calls the callback functions that have been added to an action hook. This function invokes all functions attached to action hook `$hook_name`. It is possible to create new action hooks by simply calling this function, specifying the name of the new hook using the `$hook_name` parameter. 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 ); param: string $hook_name The name of the action to be executed. param: mixed ...$arg Optional. Additional arguments which are passed on to the since: 1.2.0 since: 5.3.0 Formalized the existing and already documented `...$arg` parameter |
| do_action_ref_array( $hook_name, $args ) X-Ref |
| Calls the callback functions that have been added to an action hook, specifying arguments in an array. param: string $hook_name The name of the action to be executed. param: array $args The arguments supplied to the functions hooked to `$hook_name`. since: 2.1.0 |
| has_action( $hook_name, $callback = false ) X-Ref |
| Checks if any action has been registered for a hook. When using the `$callback` argument, this function may return a non-boolean value that evaluates to false (e.g. 0), so use the `===` operator for testing the return value. return: bool|int If `$callback` is omitted, returns boolean for whether the hook has param: string $hook_name The name of the action hook. param: callable|string|array|false $callback Optional. The callback to check for. since: 2.5.0 |
| remove_action( $hook_name, $callback, $priority = 10 ) X-Ref |
| Removes a callback function from an action hook. This can be used to remove default functions attached to a specific action hook and possibly replace them with a substitute. To remove a hook, the `$callback` and `$priority` arguments must match when the hook was added. This goes for both filters and actions. No warning will be given on removal failure. return: bool Whether the function is removed. param: string $hook_name The action hook to which the function to be removed is hooked. param: callable|string|array $callback The name of the function which should be removed. param: int $priority Optional. The exact priority used when adding the original since: 1.2.0 |
| remove_all_actions( $hook_name, $priority = false ) X-Ref |
| Removes all of the callback functions from an action hook. return: true Always returns true. param: string $hook_name The action to remove callbacks from. param: int|false $priority Optional. The priority number to remove them from. since: 2.7.0 |
| current_action() X-Ref |
| Retrieves the name of the current action hook. return: string Hook name of the current action. since: 3.9.0 |
| doing_action( $hook_name = null ) X-Ref |
| Returns whether or not an action hook is currently being processed. return: bool Whether the action is currently in the stack. param: string|null $hook_name Optional. Action hook to check. Defaults to null, since: 3.9.0 |
| did_action( $hook_name ) X-Ref |
| Retrieves the number of times an action has been fired during the current request. return: int The number of times the action hook has been fired. param: string $hook_name The name of the action hook. since: 2.1.0 |
| apply_filters_deprecated( $hook_name, $args, $version, $replacement = '', $message = '' ) X-Ref |
| Fires functions attached to a deprecated filter hook. When a filter hook is deprecated, the apply_filters() call is replaced with apply_filters_deprecated(), which triggers a deprecation notice and then fires the original filter hook. Note: the value and extra arguments passed to the original apply_filters() call must be passed here to `$args` as an array. For example: // Old filter. return apply_filters( 'wpdocs_filter', $value, $extra_arg ); // Deprecated. return apply_filters_deprecated( 'wpdocs_filter', array( $value, $extra_arg ), '4.9.0', 'wpdocs_new_filter' ); param: string $hook_name 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 empty. param: string $message Optional. A message regarding the change. Default empty. since: 4.6.0 |
| do_action_deprecated( $hook_name, $args, $version, $replacement = '', $message = '' ) X-Ref |
| Fires functions attached to a deprecated action hook. When an action hook is deprecated, the do_action() call is replaced with do_action_deprecated(), which triggers a deprecation notice and then fires the original hook. param: string $hook_name 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. Default empty. param: string $message Optional. A message regarding the change. Default empty. since: 4.6.0 |
| plugin_basename( $file ) X-Ref |
| Gets the basename of a plugin. This method extracts the name of a plugin from its filename. return: string The name of a plugin. param: string $file The filename of plugin. since: 1.5.0 |
| wp_register_plugin_realpath( $file ) X-Ref |
| Register a plugin's real path. This is used in plugin_basename() to resolve symlinked paths. return: bool Whether the path was able to be registered. param: string $file Known path to the file. since: 3.9.0 |
| plugin_dir_path( $file ) X-Ref |
| Get the filesystem directory path (with trailing slash) for the plugin __FILE__ passed in. return: string the filesystem path of the directory that contains the plugin. param: string $file The filename of the plugin (__FILE__). since: 2.8.0 |
| plugin_dir_url( $file ) X-Ref |
| Get the URL directory path (with trailing slash) for the plugin __FILE__ passed in. return: string the URL path of the directory that contains the plugin. param: string $file The filename of the plugin (__FILE__). since: 2.8.0 |
| register_activation_hook( $file, $callback ) X-Ref |
| Set the activation hook for a plugin. When a plugin is activated, the action 'activate_PLUGINNAME' hook is called. In the name of this hook, PLUGINNAME is replaced with the name of the plugin, including the optional subdirectory. For example, when the plugin is located in wp-content/plugins/sampleplugin/sample.php, then the name of this hook will become 'activate_sampleplugin/sample.php'. When the plugin consists of only one file and is (as by default) located at wp-content/plugins/sample.php the name of this hook will be 'activate_sample.php'. param: string $file The filename of the plugin including the path. param: callable $callback The function hooked to the 'activate_PLUGIN' action. since: 2.0.0 |
| register_deactivation_hook( $file, $callback ) X-Ref |
| Sets the deactivation hook for a plugin. When a plugin is deactivated, the action 'deactivate_PLUGINNAME' hook is called. In the name of this hook, PLUGINNAME is replaced with the name of the plugin, including the optional subdirectory. For example, when the plugin is located in wp-content/plugins/sampleplugin/sample.php, then the name of this hook will become 'deactivate_sampleplugin/sample.php'. When the plugin consists of only one file and is (as by default) located at wp-content/plugins/sample.php the name of this hook will be 'deactivate_sample.php'. param: string $file The filename of the plugin including the path. param: callable $callback The function hooked to the 'deactivate_PLUGIN' action. since: 2.0.0 |
| register_uninstall_hook( $file, $callback ) X-Ref |
| Sets the uninstallation hook for a plugin. Registers the uninstall hook that will be called when the user clicks on the uninstall link that calls for the plugin to uninstall itself. The link won't be active unless the plugin hooks into the action. The plugin should not run arbitrary code outside of functions, when registering the uninstall hook. In order to run using the hook, the plugin will have to be included, which means that any code laying outside of a function will be run during the uninstallation process. The plugin should not hinder the uninstallation process. If the plugin can not be written without running code within the plugin, then the plugin should create a file named 'uninstall.php' in the base plugin folder. This file will be called, if it exists, during the uninstallation process bypassing the uninstall hook. The plugin, when using the 'uninstall.php' should always check for the 'WP_UNINSTALL_PLUGIN' constant, before executing. param: string $file Plugin file. param: callable $callback The callback to run when the hook is called. Must be since: 2.7.0 |
| _wp_call_all_hook( $args ) X-Ref |
| Calls the 'all' hook, which will process the functions hooked into it. The 'all' hook passes all of the arguments or parameters that were used for the hook, which this function was called for. This function is used internally for apply_filters(), do_action(), and do_action_ref_array() and is not meant to be used from outside those functions. This function does not check for the existence of the all hook, so it will fail unless the all hook exists prior to this function call. param: array $args The collected parameters from the hook that was called. since: 2.5.0 |
| _wp_filter_build_unique_id( $hook_name, $callback, $priority ) X-Ref |
| Builds Unique ID for storage and retrieval. The old way to serialize the callback caused issues and this function is the solution. It works by checking for objects and creating a new property in the class to keep track of the object and new objects of the same class that need to be added. It also allows for the removal of actions and filters for objects after they change class properties. It is possible to include the property $wp_filter_id in your class and set it to "null" or a number to bypass the workaround. However this will prevent you from adding new classes and any new classes will overwrite the previous hook by the same class. Functions and static method callbacks are just returned as strings and shouldn't have any speed penalty. return: string Unique function ID for usage as array key. param: string $hook_name Unused. The name of the filter to build ID for. param: callable|string|array $callback The callback to generate ID for. The callback may param: int $priority Unused. The order in which the functions since: 2.2.3 since: 5.3.0 Removed workarounds for spl_object_hash(). |
| Generated: Sat Nov 23 01:00:02 2024 | Cross-referenced by PHPXref 0.7.1 |