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

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.

josantonius / hook

Maintainers

Details