bayfrontmedia / php-hooks
An easy to use hooks library for managing events and filters.
Installs: 1 159
Dependents: 1
Suggesters: 0
Security: 0
Stars: 2
Watchers: 2
Forks: 1
Open Issues: 0
Requires
- php: ^8.0
- bayfrontmedia/php-array-helpers: ^2.0
This package is auto-updated.
Last update: 2024-04-28 04:56:58 UTC
README
An easy to use hooks library for managing events and filters.
License
This project is open source and available under the MIT License.
Author
Requirements
- PHP
^8.0
Installation
composer require bayfrontmedia/php-hooks
Usage
Start using hooks
use Bayfront\Hooks\Hooks;
$hooks = new Hooks();
Public methods
Events
Filters
addEvent
Description:
Adds a hook for a given event name.
NOTE: Anonymous functions are unable to be removed with removeEvent(), so use them carefully.
Parameters:
$name(string): Name of event$function(callable)$priority = 10(int): Hooks will be executed by order of priority in ascending order (lower numbers = earlier execution)
Reserved names:
always: These hooks will always be executed wheneverdoEvent()is called, regardless of the name.destruct: These hooks will be executed when the script terminates.
Returns:
- (void)
Examples:
Anonymous function
$hooks->addEvent('name', function($name) {
echo 'My name is ' . $name;
});
Named function
function my_name($name) {
echo 'My name is ' . $name;
}
$hooks->addEvent('name', 'my_name');
Inside class scope
use Bayfront\Hooks\Hooks;
class MyClass {
protected $hooks;
public function __construct(Hooks $hooks) {
$this->hooks = $hooks;
$this->hooks->addEvent('name', [$this, 'my_name']);
}
public function my_name($name) {
echo 'My name is ' . $name;
}
}
$my_class = new MyClass($hooks);
Use variables from outside scope
$prefix = 'My name is ';
$hooks->addEvent('name', function($name) use ($prefix) {
echo $prefix . $name;
});
hasEvent
Description:
Checks if any events exist for a given name.
Parameters:
$name(string): Name of event
Returns:
- (bool)
Example:
if ($hooks->hasEvent('name')) {
// Do something
}
getEvents
Description:
Return array of all hooks for all events, or of a given event name.
Parameters:
$name = NULL(string|null): Name of event
Returns:
- (array)
Example:
print_r($hooks->getEvents()); // Returns all hooks for all events
print_r($hooks->getEvents('name')); // Returns all hooks for "name" event
removeEvent
Description:
Removes hook from a given event, if existing.
NOTE: Hooks using anonymous functions cannot be removed using this method.
Parameters:
$name(string): Name of event$function(callable): Hook to remove
Returns:
- (bool): Returns
trueif the hook existed
Example:
$hooks->removeEvent('name', 'my_name');
To remove a hook for a function from within a class scope, the $function parameter must be an array whose first value is an instance of the class, and second value is the name of the function within the class:
$hooks->removeEvent('name', [$my_class, 'my_name']);
removeEvents
Description:
Removes all hooks from a given event, if existing.
Parameters:
$name(string): Name of event
Returns:
- (bool): Returns
trueif the hook existed
Example:
$hooks->removeEvents('name');
doEvent
Description:
Execute queued hooks for a given event in order of priority.
Parameters:
$name(string): Name of event...$arg(mixed): Optional additional argument(s) to be passed to the functions hooked to the event
Returns:
- (void)
Example:
$hooks->doEvent('name', 'John');
addFilter
Description:
Adds a hook for a given filter name.
Parameters:
$name(string): Name of filter$function(callable)$priority = 10(int): Filters will be executed in order of priority in ascending order (lower numbers = earlier execution)
Returns:
- (void)
Examples:
Anonymous function
$hooks->addFilter('name', function($name) {
return strtoupper($name);
});
Named function
function uppercase($name) {
return strtoupper($name);
}
$hooks->addFilter('name', 'uppercase');
Inside class scope
use Bayfront\Hooks\Hooks;
class MyClass {
protected $hooks;
public function __construct(Hooks $hooks) {
$this->hooks = $hooks;
$this->hooks->addFilter('name', [$this, 'uppercase']);
}
public function uppercase($name) {
return strtoupper($name);
}
}
$my_class = new MyClass($hooks);
Use variables from outside scope
$prefix = 'My name is ';
$hooks->addFilter('name', function($name) use ($prefix) {
return strtoupper($prefix . $name);
});
hasFilter
Description:
Checks if any filters exist for a given name.
Parameters:
$name(string): Name of filter
Returns:
- (bool)
Example:
if ($hooks->hasFilter('name')) {
// Do something
}
getFilters
Description:
Return array of all hooks for all filters, or of a given filter name.
Parameters:
$name = NULL(string|null): Name of filter
Returns:
- (array)
Example:
print_r($hooks->getFilters()); // Returns all hooks for all filters
print_r($hooks->getFilters('name')); // Returns all hooks for "name" filter
removeFilter
Description:
Removes hook from a given filter, if existing.
NOTE: Hooks using anonymous functions cannot be removed using this method
Parameters:
$name(string): Name of filter$function(callable): Hook to remove
Returns:
- (bool): Returns
trueif the hook existed
Example:
$hooks->removeFilter('name', 'uppercase');
To remove a hook for a function from within a class scope, the $function parameter must be an array whose first value is an instance of the class, and second value is the name of the function within the class:
$hooks->removeFilter('name', [$my_class, 'uppercase']);
removeFilters
Description:
Removes all hooks from a given filter, if existing.
Parameters:
$name(string): Name of filter
Returns:
- (bool): Returns
trueif the hook existed
Example:
$hooks->removeFilters('name');
doFilter
Description:
Filters value through queued filters in order of priority.
Parameters:
$name(string): Name of filter$value(mixed): Original value to be filtered
Returns:
- (mixed): Filtered value
Example:
echo $hooks->doFilter('name', 'John');