PHPackages                             josantonius/hook - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. josantonius/hook

ActiveLibrary[Utility & Helpers](/categories/utility)

josantonius/hook
================

Library for handling hooks.

v2.0.3(3y ago)222.0k810MITPHPPHP ^8.0

Since Mar 16Pushed 3y ago3 watchersCompare

[ Source](https://github.com/josantonius/php-hook)[ Packagist](https://packagist.org/packages/josantonius/hook)[ GitHub Sponsors](https://github.com/Josantonius)[ RSS](/packages/josantonius-hook/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (3)Versions (17)Used By (10)

PHP Hook library
================

[](#php-hook-library)

[![Latest Stable Version](https://camo.githubusercontent.com/cd9b2f9e46dd26379b3793824c31bd316b6d65a40a61c5dfdbbb19eb00ed350e/68747470733a2f2f706f7365722e707567782e6f72672f6a6f73616e746f6e6975732f686f6f6b2f762f737461626c65)](https://packagist.org/packages/josantonius/hook)[![License](https://camo.githubusercontent.com/e632309ad92eff01b056acab883447161bdedc31875a03d65d1e0458f6a24429/68747470733a2f2f706f7365722e707567782e6f72672f6a6f73616e746f6e6975732f686f6f6b2f6c6963656e7365)](LICENSE)[![Total Downloads](https://camo.githubusercontent.com/182d1d18dca99b100f3ea9f0727335e64caf065c80ce29b4f8f4e1614fa1b4f8/68747470733a2f2f706f7365722e707567782e6f72672f6a6f73616e746f6e6975732f686f6f6b2f646f776e6c6f616473)](https://packagist.org/packages/josantonius/hook)[![CI](https://github.com/josantonius/php-hook/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/josantonius/php-hook/actions/workflows/ci.yml)[![CodeCov](https://camo.githubusercontent.com/1d7cf8657efd4fbf2e2aa826114d10f3a3a0de0cff13b0b41c3ed63aa97c08d5/68747470733a2f2f636f6465636f762e696f2f67682f6a6f73616e746f6e6975732f7068702d686f6f6b2f6272616e63682f6d61696e2f67726170682f62616467652e737667)](https://codecov.io/gh/josantonius/php-hook)[![PSR1](https://camo.githubusercontent.com/b502a899c9aec217e98971160f816f87346be272cf1a25cfa4793f2ee724bfc8/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5053522d312d6635373034362e737667)](https://www.php-fig.org/psr/psr-1/)[![PSR4](https://camo.githubusercontent.com/d1c090de87e968254a6658528f3bfe9c9dad422d6047fd1323dc211560182c01/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5053522d342d3962353962362e737667)](https://www.php-fig.org/psr/psr-4/)[![PSR12](https://camo.githubusercontent.com/19c529c6dc0656dcc2a16c1a84af450b7bd0dc7b0571b8f17e4fc9f2414f8821/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5053522d31322d3161626339632e737667)](https://www.php-fig.org/psr/psr-12/)

**Translations**: [Español](.github/lang/es-ES/README.md)

Library for handling hooks in PHP.

---

- [Requirements](#requirements)
- [Installation](#installation)
- [Available Classes](#available-classes)
    - [Action Instance](#action-instance)
    - [Hook Class](#hook-class)
    - [Priority Class](#priority-class)
- [Exceptions Used](#exceptions-used)
- [Usage](#usage)
- [Tests](#tests)
- [TODO](#todo)
- [Changelog](#changelog)
- [Contribution](#contribution)
- [Sponsor](#sponsor)
- [License](#license)

---

Requirements
------------

[](#requirements)

- Operating System: Linux | Windows.
- PHP versions: 8.1 | 8.2.

Installation
------------

[](#installation)

The preferred way to install this extension is through [Composer](http://getcomposer.org/download/).

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

[](#available-classes)

### Action Instance

[](#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

[](#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

[](#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
---------------

[](#exceptions-used)

```
use Josantonius\Hook\Exceptions\HookException;
```

Usage
-----

[](#usage)

Example of use for this library:

### Register new hook

[](#register-new-hook)

```
use Josantonius\Hook\Hook;

$hook = new Hook('name');
```

### Adds actions on the hook

[](#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

[](#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

[](#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

[](#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

[](#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

[](#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

[](#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

[](#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

[](#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

[](#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

[](#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

[](#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

[](#gets-hook-name)

```
use Josantonius\Hook\Hook;

$hook = new Hook('foo');

$name = $hook->getName(); // foo
```

#### Gets action priority

[](#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

[](#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

[](#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

[](#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
-----

[](#tests)

To run [tests](tests) you just need [composer](http://getcomposer.org/download/)and to execute the following:

```
git clone https://github.com/josantonius/php-hook.git
```

```
cd php-hook
```

```
composer install
```

Run unit tests with [PHPUnit](https://phpunit.de/):

```
composer phpunit
```

Run code standard tests with [PHPCS](https://github.com/squizlabs/PHP_CodeSniffer):

```
composer phpcs
```

Run [PHP Mess Detector](https://phpmd.org/) tests to detect inconsistencies in code style:

```
composer phpmd
```

Run all previous tests:

```
composer tests
```

TODO
----

[](#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
---------

[](#changelog)

Detailed changes for each release are documented in the [release notes](https://github.com/josantonius/php-hook/releases).

Contribution
------------

[](#contribution)

Please make sure to read the [Contributing Guide](.github/CONTRIBUTING.md), before making a pull request, start a discussion or report a issue.

Thanks to all [contributors](https://github.com/josantonius/php-hook/graphs/contributors)! ❤️

Sponsor
-------

[](#sponsor)

If this project helps you to reduce your development time, [you can sponsor me](https://github.com/josantonius#sponsor) to support my open source work 😊

License
-------

[](#license)

This repository is licensed under the [MIT License](LICENSE).

Copyright © 2017-present, [Josantonius](https://github.com/josantonius#contact)

###  Health Score

40

—

FairBetter than 88% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity29

Limited adoption so far

Community20

Small or concentrated contributor base

Maturity76

Established project with proven stability

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~144 days

Recently: every ~431 days

Total

15

Last Release

1327d ago

Major Versions

1.1.0 → v2.0.02022-07-30

PHP version history (3 changes)1.0.0PHP >=5.6

1.0.1PHP ^5.6 || ^7.0

v2.0.0PHP ^8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/4b221283501ec8a9cbaefaf27821a91ae8ddd33bddf1fccc6c6815b7ad216ff1?d=identicon)[Josantonius](/maintainers/Josantonius)

---

Top Contributors

[![josantonius](https://avatars.githubusercontent.com/u/18104336?v=4)](https://github.com/josantonius "josantonius (80 commits)")

---

Tags

actionshandling-hooksphpphp-hooksphpHOOKactionsaction-hooks

###  Code Quality

TestsPHPUnit

Code StylePHP\_CodeSniffer

### Embed Badge

![Health badge](/badges/josantonius-hook/health.svg)

```
[![Health](https://phpackages.com/badges/josantonius-hook/health.svg)](https://phpackages.com/packages/josantonius-hook)
```

###  Alternatives

[tormjens/eventy

The WordPress filter/action system in Laravel

438912.9k16](/packages/tormjens-eventy)[nilportugues/php_backslasher

Adds all PHP internal functions to its namespace by adding backslash to them. Improves the application's performance when OPCache is on.

889.3k18](/packages/nilportugues-php-backslasher)[imanghafoori/laravel-anypass

A minimal yet powerful package to help you in development.

21421.6k](/packages/imanghafoori-laravel-anypass)[nilportugues/php_todo

Looks into the code using a user-defined list of to-do phrases and stops commit if the total amount increased or is above a threshold.

1210.0k](/packages/nilportugues-php-todo)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)