[ Index ]

PHP Cross Reference of WordPress trunk

title

Body

[close]

/wp-includes/ -> plugin.php (summary)

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: 599 lines (22 kb)
Included or required: 1 time
Referenced: 0 times
Includes or requires: 0 files

Defines 16 functions

  add_filter()
  has_filter()
  apply_filters()
  remove_filter()
  current_filter()
  add_action()
  do_action()
  did_action()
  do_action_ref_array()
  has_action()
  remove_action()
  plugin_basename()
  register_activation_hook()
  register_deactivation_hook()
  _wp_call_all_hook()
  _wp_filter_build_unique_id()

Functions
Functions that are not part of a class:

add_filter($tag, $function_to_add, $priority = 10, $accepted_args = 1)   X-Ref
add_filter() - Hooks a function or method to a specific filter action.

Filters are the hooks that WordPress launches to modify text of various types
before adding it to the database or sending it to the browser screen. Plugins
can specify that one or more of its PHP functions is executed to
modify specific types of text at these times, using the Filter API.

To use the API, the following code should be used to bind a callback to the filter
<code>
function example_hook($example) { echo $example; }

add_filter('example_filter', 'example_hook');
</code>

In WordPress 1.5.1+, hooked functions can take extra arguments that are set when
the matching do_action() or apply_filters() call is run. The <tt>$accepted_args
allow for calling functions only when the number of args match. Hooked functions
can take extra arguments that are set when the matching <tt>do_action()</tt> or
<tt>apply_filters()</tt> call is run. For example, the action <tt>comment_id_not_found</tt>
will pass any functions that hook onto it the ID of the requested comment.

<strong>Note:</strong> the function will return true no matter if the function was hooked
fails or not. There are no checks for whether the function exists beforehand and no checks
to whether the <tt>$function_to_add is even a string. It is up to you to take care and
this is done for optimization purposes, so everything is as quick as possible.

param: string $tag The name of the filter to hook the <tt>$function_to_add</tt> to.
param: callback $function_to_add The name of the function to be called 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). 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.
param: int $accepted_args optional. The number of arguments the function accept (default 1).
return: boolean true

has_filter($tag, $function_to_check = false)   X-Ref
has_filter() - Check if any filter has been registered for a hook.

param: string $tag The name of the filter hook.
param: callback $function_to_check optional.  If specified, return the priority of that function on this hook or false if not attached.
return: int|boolean Optionally returns the priority on that hook for the specified function.

apply_filters($tag, $value)   X-Ref
apply_filters() - Call the functions added to a filter hook.

The callback functions attached to filter hook <tt>$tag</tt> 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 <tt>$tag</a> parameter.

The function allows for additional arguments to be added and passed to hooks.
<code>
function example_hook($string, $arg1, $arg2)
{
//Do stuff
return $string;
}
$value = apply_filters('example_filter', 'filter me', 'arg1', 'arg2');
</code>

param: string $tag The name of the filter hook.
param: mixed $value The value on which the filters hooked to <tt>$tag</tt> are applied on.
param: mixed $var,... Additional variables passed to the functions hooked to <tt>$tag</tt>.
return: mixed The filtered value after all hooked functions are applied to it.

remove_filter($tag, $function_to_remove, $priority = 10, $accepted_args = 1)   X-Ref
remove_filter() - Removes a function from a specified filter hook.

This function removes a function attached to a specified filter hook. This
method 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 <tt>$function_to_remove</tt> and <tt>$priority</tt> arguments
must match when the hook was added. This goes for both filters and actions. No warning
will be given on removal failure.

param: string $tag The filter hook to which the function to be removed is hooked.
param: callback $function_to_remove The name of the function which should be removed.
param: int $priority optional. The priority of the function (default: 10).
param: int $accepted_args optional. The number of arguments the function accpets (default: 1).
return: boolean Whether the function existed before it was removed.

current_filter()   X-Ref
current_filter() - Return the name of the current filter or action.

return: string Hook name of the current filter or action.

add_action($tag, $function_to_add, $priority = 10, $accepted_args = 1)   X-Ref
add_action() - Hooks a function on to a specific action.

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.

param: string $tag The name of the action to which the <tt>$function_to-add</tt> is hooked.
param: callback $function_to_add The name of the function you wish to be called.
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.
param: int $accepted_args optional. The number of arguments the function accept (default 1).

do_action($tag, $arg = '')   X-Ref
do_action() - Execute functions hooked on a specific action hook.

This function invokes all functions attached to action hook <tt>$tag</tt>.
It is possible to create new action hooks by simply calling this function,
specifying the name of the new hook using the <tt>$tag</tt> parameter.

You can pass extra arguments to the hooks, much like you can with apply_filters().

param: string $tag The name of the action to be executed.
param: mixed $arg,... Optional additional arguments which are passed on to the functions hooked to the action.
return: null Will return null if $tag does not exist in $wp_filter array

did_action($tag)   X-Ref
did_action() - Return the number times an action is fired.

param: string $tag The name of the action hook.
return: int The number of times action hook <tt>$tag</tt> is fired

do_action_ref_array($tag, $args)   X-Ref
do_action_ref_array() - Execute functions hooked on a specific action hook, specifying arguments in an array.

param: string $tag The name of the action to be executed.
param: array $args The arguments supplied to the functions hooked to <tt>$tag</tt>
return: null Will return null if $tag does not exist in $wp_filter array

has_action($tag, $function_to_check = false)   X-Ref
has_action() - Check if any action has been registered for a hook.

param: string $tag The name of the action hook.
param: callback $function_to_check optional.  If specified, return the priority of that function on this hook or false if not attached.
return: int|boolean Optionally returns the priority on that hook for the specified function.

remove_action($tag, $function_to_remove, $priority = 10, $accepted_args = 1)   X-Ref
remove_action() - Removes a function from a specified action hook.

This function removes a function attached to a specified action hook. This
method can be used to remove default functions attached to a specific filter
hook and possibly replace them with a substitute.

param: string $tag The action hook to which the function to be removed is hooked.
param: callback $function_to_remove The name of the function which should be removed.
param: int $priority optional The priority of the function (default: 10).
param: int $accepted_args optional. The number of arguments the function accpets (default: 1).
return: boolean Whether the function is removed.

plugin_basename($file)   X-Ref
plugin_basename() - Gets the basename of a plugin.

This method extracts the name of a plugin from its filename.

param: string $file The filename of plugin.
return: string The name of a plugin.

register_activation_hook($file, $function)   X-Ref
register_activation_hook() - Hook a function on a plugin activation action hook.

When a plugin is activated, the action 'activate_PLUGINNAME' hook is
activated. 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 <tt>wp-content/plugin/sampleplugin/sample.php</tt>, 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
<tt>wp-content/plugin/sample.php</tt> the name of this hook will be
'activate_sample.php'.

param: string $file The filename of the plugin including the path.
param: string $function the function hooked to the 'activate_PLUGIN' action.

register_deactivation_hook($file, $function)   X-Ref
register_deactivation_hook() - Hook a function on a plugin deactivation action hook.

When a plugin is deactivated, the action 'deactivate_PLUGINNAME' hook is
deactivated. 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 <tt>wp-content/plugin/sampleplugin/sample.php</tt>, 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
<tt>wp-content/plugin/sample.php</tt> the name of this hook will be
'activate_sample.php'.

param: string $file The filename of the plugin including the path.
param: string $function the function hooked to the 'activate_PLUGIN' action.

_wp_call_all_hook($args)   X-Ref
_wp_call_all_hook() - 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.
param: string $hook Optional. The hook name that was used to call the 'all' hook.

_wp_filter_build_unique_id($tag, $function, $priority)   X-Ref
_wp_filter_build_unique_id() - Build 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 an 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.

param: string $tag Used in counting how many hooks were applied
param: string|array $function Used for creating unique id
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.
param: string $type filter or action
return: string Unique ID for usage as array key



Generated: Tue Aug 5 00:17:06 2008 Cross-referenced by PHPXref 0.7