[](https://github.com/voku/php-hooks/actions/workflows/ci.yml)
[](https://coveralls.io/github/voku/php-hooks?branch=master)
[](https://www.codacy.com/app/voku/php-hooks)
[](https://packagist.org/packages/voku/php-hooks)
[](https://packagist.org/packages/voku/php-hooks)
[](https://packagist.org/packages/voku/php-hooks)
PHP-Hooks
=========
The PHP Hooks Class is a fork of the WordPress filters hook system rolled in to a class to be ported into any php based system
* This class is heavily based on the WordPress plugin API and most (if not all) of the code comes from there.
How to install?
=====
```shell
composer require voku/php-hooks
```
How to use?
=====
We start with a simple example ...
```php
add_action('header_action','echo_this_in_header');
function echo_this_in_header(){
echo 'this came from a hooked function';
}
```
then all that is left for you is to call the hooked function when you want anywhere in your application, EX:
```php
';
$hooks->do_action('header_action');
echo '';
```
and you output will be: ``
PS: you can also use method from a class for a hook e.g.: `$hooks->add_action('header_action', array($this, 'echo_this_in_header_via_method');`
Important Note: Shared Hook Namespace
======================================
Actions and filters in this library share the **same internal registry**, keyed by hook name (tag). This means that if you register an action and a filter with the same name, **both will be triggered** regardless of whether you call `do_action()` or `apply_filters()`.
Example:
```php
add_action('myHook', function () {
echo 'action triggered';
});
$hooks->do_action('myHook'); // triggers the callback → "action triggered"
$hooks->apply_filters('myHook', null); // also triggers the callback → "action triggered"
```
To avoid unexpected cross-triggering, use distinct names for actions and filters (e.g. prefix them: `action_myHook` vs `filter_myHook`).
See the [`testSharedNamespaceBetweenActionsAndFilters`](tests/HooksTest.php) test for a working example of this behaviour.
Methods
=======
**ACTIONS:**
**add_action** Hooks a function on to a specific action.
- @access public
- @since 0.1
- @param string $tag The name of the action to which the $function_to_add 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** Execute functions hooked on a specific action hook.
- @access public
- @since 0.1
- @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
**remove_action** Removes a function from a specified action hook.
- @access public
- @since 0.1
- @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).
- @return boolean Whether the function is removed.
**has_action** Check if any action has been registered for a hook.
- @access public
- @since 0.1
- @param string $tag The name of the action hook.
- @param callback $function_to_check optional.
- @return mixed If $function_to_check is omitted, returns boolean for whether the hook has anything registered.
When checking a specific function, the priority of that hook is returned, or false if the function is not attached.
When using the $function_to_check 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.
**did_action** Retrieve the number of times an action is fired.
- @access public
- @since 0.1
- @param string $tag The name of the action hook.
- @return int The number of times action hook $tag is fired
**FILTERS:**
**add_filter** Hooks a function or method to a specific filter action.
- @access public
- @since 0.1
- @param string $tag The name of the filter to hook the $function_to_add 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
**remove_filter** Removes a function from a specified filter hook.
- @access public
- @since 0.1
- @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 accepts (default: 1).
- @return boolean Whether the function existed before it was removed.
**has_filter** Check if any filter has been registered for a hook.
- @access public
- @since 0.1
- @param string $tag The name of the filter hook.
- @param callback $function_to_check optional.
- @return mixed If $function_to_check is omitted, returns boolean for whether the hook has anything registered.
When checking a specific function, the priority of that hook is returned, or false if the function is not attached.
When using the $function_to_check 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.
**apply_filters** Call the functions added to a filter hook.
- @access public
- @since 0.1
- @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 $var,... Additional variables passed to the functions hooked to $tag.
- @return mixed The filtered value after all hooked functions are applied to it.
License
=======
Since this class is derived from the WordPress Plugin API so are the license and they are GPL http://www.gnu.org/licenses/gpl.html
[1]: https://github.com/bainternet/PHP-Hooks/zipball/master
[2]: https://github.com/bainternet/PHP-Hooks/tarball/master
[3]: http://bainternet.github.com/PHP-Hooks/