PHP Hook library

Translations: Español

Library for handling hooks in PHP.

Version 1.x is considered as deprecated and unsupported. In this version (2.x) the library was completely restructured. It is recommended to review the documentation for this version and make the necessary changes before starting to use it, as it not be compatible with version 1.x.

Requirements
Installation
Available Classes and Instances
Quick Start
Usage
Tests
TODO
Changelog
Contribution
Sponsor
License

Requirements

This library is compatible with the PHP versions: 8.1.

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 and Instances

Hook Class

Available methods:

Register new hook

$hook = new Hook(string $name);

Adds action on the hook

$hook->addAction(callable $callback, int $priority = Priority::NORMAL): Action

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 for more information about first class callable syntax.

@return Action added.

Adds action once on the hook

$hook->addActionOnce(callable $callback, int $priority = Priority::NORMAL): Action

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.

Runs the added actions for the hook

$hook->doActions(mixed ...$arguments): Action[]

@throws HookException if the actions have already been done.

@throws HookException if no actions were added for the hook.

@return array Actions done.

Checks if the hook has actions

$hook->hasActions(): bool

True if the hook has any action even if the action has been done before (recurring actions created with addAction).

Checks if the hook has undone actions

$hook->hasUndoneActions(): bool

True if the hook has some action left undone.

Checks if the actions were done at least once

$hook->hasDoneActions(): bool

If doActions was executed at least once.

Gets hook name

$hook->getName(): string

Action Instance

Available methods:

Gets action priority

$action->getPriority(): int

Gets action callback result

$action->getResult(): mixed

Checks if the action is done once

$action->isOnce(): bool

Checks if the action has already been done

$action->wasDone(): bool

Priority Class

Available constants:

Priority::HIGHEST; // 50
Priority::HIGH;    // 100
Priority::NORMAL;  // 150
Priority::LOW;     // 200
Priority::LOWEST;  // 250

Quick Start

To use this library with Composer:

require __DIR__ . '/vendor/autoload.php';

use Josantonius\Hook\Hook;
use Josantonius\Hook\Priority;

Usage

Example of use for this library:

- Register new hook

$hook = new Hook('foo');

- Adds actions on the hook

$hook->addAction(foo(...));

$hook->addAction(Foo::bar(...), Priority::HIGH);

- Adds actions once on the hook

$hook->addActionOnce(bar(...));

$hook->addActionOnce($foo->bar(...), Priority::LOWEST);

- Runs the added actions for the hook

Do actions with the same priority

$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

$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

$hook->addAction(foo(...));

$hook->doActions('foo', 'bar');

Do actions recurrently

$hook->addAction(one(...));
$hook->addAction(tho(...));
$hook->addActionOnce(three(...)); // Will be done only once

$hook->doActions(); // one(), two(), three()

$hook->doActions(); // one(), two()

Do actions only once

$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

$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

$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

$hook->addAction(foo());

$hook->hasDoneActions(); // false

$hook->doActions();

$hook->hasDoneActions(); // True since the actions were done

- Gets hook name

$name = $hook->getName();

- Gets action priority

$action = $hook->addAction(foo());

$action->getPriority();

- Gets action callback result

$action = $hook->addAction(foo());

$action->getResult();

- Checks if the action is done once

$action = $hook->addAction(foo());

$action->isOnce(); // false

$action = $hook->addActionOnce(foo());

$action->isOnce(); // true

- Checks if the action has already been done

$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 PSR12 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.

Files

README.md

Latest commit

History