README

Translations: Español

Library for handling hooks in PHP.

• Requirements
• Installation
• Available Classes
  • Action Instance
  • Hook Class
  • Priority Class
• 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