josantonius / hook
Library for handling hooks.
Fund package maintenance!
Josantonius
Installs: 1 785
Dependents: 9
Suggesters: 0
Security: 0
Stars: 22
Watchers: 4
Forks: 8
Open Issues: 0
Requires
- php: ^8.0
Requires (Dev)
- phpmd/phpmd: ^2.6
- phpunit/phpunit: ^9.5
- squizlabs/php_codesniffer: ^3.7
README
Translations: Español
Library for handling hooks in PHP.
- Requirements
- Installation
- Available Classes
- Exceptions Used
- Usage
- Tests
- TODO
- Changelog
- Contribution
- Sponsor
- License
Requirements
-
Operating System: Linux | Windows.
-
PHP versions: 8.1 | 8.2.
Installation
The preferred way to install this extension is through Composer.
To install PHP Hook library, simply:
composer require josantonius/hook
The previous command will only install the necessary files, if you prefer to download the entire source code you can use:
composer require josantonius/hook --prefer-source
You can also clone the complete repository with Git:
git clone https://github.com/josantonius/php-hook.git
Available Classes
Action Instance
Josantonius\Hook\Action
Gets action priority:
public function getPriority(): int;
Gets action callback result:
public function getResult(): mixed;
Checks if the action is done once:
public function isOnce(): bool;
Checks if the action has already been done:
public function wasDone(): bool;
Hook Class
Josantonius\Hook\Hook
Register new hook:
public function __construct(private string $name);
Adds action on the hook:
/** * Action will be maintained after performing actions and will be available if are done again. * * @see https://www.php.net/manual/en/functions.first_class_callable_syntax.php * * @return Action Added action. */ public function addAction(callable $callback, int $priority = Priority::NORMAL): Action;
Adds action once on the hook:
/** * Action will only be done once and will be deleted after it is done. * * It is recommended to use this method to release the actions * from memory if the hook actions will only be done once. * * @return Action Added action. */ public function addActionOnce(callable $callback, int $priority = Priority::NORMAL): Action;
Runs the added actions for the hook:
/** * @throws HookException if the actions have already been done. * @throws HookException if no actions were added for the hook. * * @return Action[] Done actions. */ public function doActions(mixed ...$arguments): array;
Checks if the hook has actions:
/** * True if the hook has any action even if the action has been * done before (recurring actions created with addAction). */ public function hasActions(): bool;
Checks if the hook has undone actions:
/** * True if the hook has some action left undone. */ public function hasUndoneActions(): bool;
Checks if the actions were done at least once:
/** * If doActions was executed at least once. */ public function hasDoneActions(): bool;
Gets hook name:
public function getName(): string;
Priority Class
Josantonius\Hook\Priority
Available constants:
public const HIGHEST = 50; public const HIGH = 100; public const NORMAL = 150; public const LOW = 200; public const LOWEST = 250;
Exceptions Used
use Josantonius\Hook\Exceptions\HookException;
Usage
Example of use for this library:
Register new hook
use Josantonius\Hook\Hook; $hook = new Hook('name');
Adds actions on the hook
use Josantonius\Hook\Hook; class Foo { public static function bar() { /* do something */ } public static function baz() { /* do something */ } } $hook = new Hook('name'); $hook->addAction(Foo::bar(...)); $hook->addAction(Foo::baz(...));
Add actions with custom priority in the hook
use Josantonius\Hook\Hook; use Josantonius\Hook\Priority; class Foo { public static function bar() { /* do something */ } public static function baz() { /* do something */ } } $hook = new Hook('name'); $hook->addAction(Foo::bar(...), Priority::LOW); $hook->addAction(Foo::baz(...), Priority::HIGH);
Adds actions once on the hook
use Josantonius\Hook\Hook; class Foo { public function bar() { /* do something */ } public function baz() { /* do something */ } } $foo = new Foo(); $hook = new Hook('name'); $hook->addActionOnce($foo->bar(...)); $hook->addActionOnce($foo->baz(...));
Adds actions once with custom priority in the hook
use Josantonius\Hook\Hook; use Josantonius\Hook\Priority; class Foo { public function bar() { /* do something */ } public function baz() { /* do something */ } } $foo = new Foo(); $hook = new Hook('name'); $hook->addActionOnce($foo->bar(...), Priority::LOW); $hook->addActionOnce($foo->baz(...), Priority::HIGH);
Do actions with the same priority
use Josantonius\Hook\Hook; function one() { /* do something */ } function two() { /* do something */ } $hook = new Hook('name'); $hook->addAction(one(...)); $hook->addAction(two(...)); /** * The actions will be executed according to their natural order: * * one(), two()... */ $hook->doActions();
Do actions with different priority
use Josantonius\Hook\Hook; use Josantonius\Hook\Priority; function a() { /* do something */ } function b() { /* do something */ } function c() { /* do something */ } $hook = new Hook('name'); $hook->addAction(a(...), priority::LOW); $hook->addAction(b(...), priority::NORMAL); $hook->addAction(c(...), priority::HIGHEST); /** * Actions will be executed according to their priority: * * c(), b(), a()... */ $hook->doActions();
Do actions with arguments
use Josantonius\Hook\Hook; function foo($foo, $bar) { /* do something */ } $hook = new Hook('name'); $hook->addAction(foo(...)); $hook->doActions('foo', 'bar');
Do actions recurrently
use Josantonius\Hook\Hook; function a() { /* do something */ } function b() { /* do something */ } function c() { /* do something */ } $hook = new Hook('name'); $hook->addAction(a(...)); $hook->addAction(b(...)); $hook->addActionOnce(c(...)); // Will be done only once $hook->doActions(); // a(), b(), c() $hook->doActions(); // a(), b()
Do actions only once
use Josantonius\Hook\Hook; function one() { /* do something */ } function two() { /* do something */ } $hook = new Hook('name'); $hook->addActionOnce(one(...)); $hook->addActionOnce(tho(...)); $hook->doActions(); // $hook->doActions(); Throw exception since there are no actions to be done
Checks if the hook has actions
use Josantonius\Hook\Hook; function foo() { /* do something */ } $hook = new Hook('name'); $hook->addAction(foo()); $hook->hasActions(); // true $hook->doActions(); $hook->hasActions(); // True since the action is recurrent and remains stored
Checks if the hook has undone actions
use Josantonius\Hook\Hook; function foo() { /* do something */ } $hook = new Hook('name'); $hook->addAction(foo()); $hook->hasUndoneActions(); // true $hook->doActions(); $hook->hasUndoneActions(); // False since there are no undone actions
Checks if the actions were done at least once
use Josantonius\Hook\Hook; function foo() { /* do something */ } $hook = new Hook('name'); $hook->addAction(foo()); $hook->hasDoneActions(); // false $hook->doActions(); $hook->hasDoneActions(); // True since the actions were done
Gets hook name
use Josantonius\Hook\Hook; $hook = new Hook('foo'); $name = $hook->getName(); // foo
Gets action priority
use Josantonius\Hook\Hook; function foo() { /* do something */ } $hook = new Hook('name'); $action = $hook->addAction(foo()); $action->getPriority();
Gets action callback result
use Josantonius\Hook\Hook; function foo() { /* do something */ } $hook = new Hook('name'); $action = $hook->addAction(foo()); $action->getResult();
Checks if the action is done once
use Josantonius\Hook\Hook; function foo() { /* do something */ } $hook = new Hook('name'); $action = $hook->addAction(foo()); $action->isOnce(); // false $action = $hook->addActionOnce(foo()); $action->isOnce(); // true
Checks if the action has already been done
use Josantonius\Hook\Hook; function foo() { /* do something */ } $hook = new Hook('name'); $action = $hook->addAction(foo()); $action->wasDone(); // false $hook->doActions(); $action->wasDone(); // true
Tests
To run tests you just need composer and to execute the following:
git clone https://github.com/josantonius/php-hook.git
cd php-hook
composer install
Run unit tests with PHPUnit:
composer phpunit
Run code standard tests with PHPCS:
composer phpcs
Run PHP Mess Detector tests to detect inconsistencies in code style:
composer phpmd
Run all previous tests:
composer tests
TODO
- Add new feature
- Improve tests
- Improve documentation
- Improve English translation in the README file
- Refactor code for disabled code style rules (see phpmd.xml and phpcs.xml)
- Make Action->runCallback() accessible only to the Hook class
- Add method to remove action?
- Add option to add ID in actions?
Changelog
Detailed changes for each release are documented in the release notes.
Contribution
Please make sure to read the Contributing Guide, before making a pull request, start a discussion or report a issue.
Thanks to all contributors! ❤️
Sponsor
If this project helps you to reduce your development time, you can sponsor me to support my open source work 😊
License
This repository is licensed under the MIT License.
Copyright © 2017-present, Josantonius