2017 © Pedro Peláez
 

library hook

Library for handling hooks.

image

josantonius/hook

Library for handling hooks.

  • PHP
  • 10 Dependents
  • 0 Suggesters
  • 3 Forks
  • 0 Open issues
  • 12 Versions
  • 1 % Grown

The README.md

PHP Hook library

Latest Stable Version License Total Downloads CI CodeCov PSR1 PSR4 PSR12, (*1)

Translations: Español, (*2)

Library for handling hooks in PHP., (*3)

Requirements

  • Operating System: Linux | Windows., (*4)

  • PHP versions: 8.1 | 8.2., (*5)

Installation

The preferred way to install this extension is through Composer., (*6)

To install PHP Hook library, simply:, (*7)

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:, (*8)

composer require josantonius/hook --prefer-source

You can also clone the complete repository with Git:, (*9)

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

Available Classes

Action Instance

Josantonius\Hook\Action, (*10)

Gets action priority:, (*11)

public function getPriority(): int;

Gets action callback result:, (*12)

public function getResult(): mixed;

Checks if the action is done once:, (*13)

public function isOnce(): bool;

Checks if the action has already been done:, (*14)

public function wasDone(): bool;

Hook Class

Josantonius\Hook\Hook, (*15)

Register new hook:, (*16)

public function __construct(private string $name);

Adds action on the hook:, (*17)

/**
 * 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:, (*18)

/**
 * 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:, (*19)

/**
 * @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:, (*20)

/**
 * 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:, (*21)

/**
 * True if the hook has some action left undone.
 */
public function hasUndoneActions(): bool;

Checks if the actions were done at least once:, (*22)

/**
 * If doActions was executed at least once.
 */
public function hasDoneActions(): bool;

Gets hook name:, (*23)

public function getName(): string;

Priority Class

Josantonius\Hook\Priority, (*24)

Available constants:, (*25)

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:, (*26)

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:, (*27)

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

cd php-hook

composer install

Run unit tests with PHPUnit:, (*28)

composer phpunit

Run code standard tests with PHPCS:, (*29)

composer phpcs

Run PHP Mess Detector tests to detect inconsistencies in code style:, (*30)

composer phpmd

Run all previous tests:, (*31)

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., (*32)

Contribution

Please make sure to read the Contributing Guide, before making a pull request, start a discussion or report a issue., (*33)

Thanks to all contributors! :heart:, (*34)

If this project helps you to reduce your development time, you can sponsor me to support my open source work :blush:, (*35)

License

This repository is licensed under the MIT License., (*36)

Copyright © 2017-present, Josantonius, (*37)

The Versions

06/01 2018

dev-master

9999999-dev

Library for handling hooks.

  Sources   Download

MIT

The Requires

  • php ^5.6 || ^7.0

 

The Development Requires

by Avatar Josantonius

hook php hhvm actions action hooks

06/01 2018

1.1.0

1.1.0.0

Library for handling hooks.

  Sources   Download

MIT

The Requires

  • php ^5.6 || ^7.0

 

The Development Requires

by Avatar Josantonius

hook php hhvm actions action hooks

12/11 2017

1.0.9

1.0.9.0

Library for handling hooks.

  Sources   Download

MIT

The Requires

  • php ^5.6 || ^7.0

 

The Development Requires

by Avatar Josantonius

hook php hhvm actions action hooks

30/10 2017

1.0.8

1.0.8.0

Library for handling hooks.

  Sources   Download

MIT

The Requires

  • php ^5.6 || ^7.0

 

The Development Requires

by Avatar Josantonius

hook php hhvm actions action hooks

18/10 2017

1.0.7

1.0.7.0

Library for handling hooks.

  Sources   Download

MIT

The Requires

  • php ^5.6 || ^7.0

 

The Development Requires

by Avatar Josantonius

hook php hhvm actions action hooks

12/10 2017

1.0.6

1.0.6.0

Library for handling hooks.

  Sources   Download

MIT

The Requires

  • php ^5.6 || ^7.0

 

The Development Requires

by Avatar Josantonius

hook php hhvm actions action hooks

16/07 2017

1.0.5

1.0.5.0

Library for handling hooks.

  Sources   Download

MIT

The Requires

  • php ^5.6 || ^7.0

 

by Avatar Josantonius

hook php hhvm actions action hooks

02/06 2017

1.0.4

1.0.4.0

Library for handling hooks.

  Sources   Download

MIT

The Requires

  • php ^5.6 || ^7.0

 

by Avatar Josantonius

hook php hhvm actions action hooks

31/05 2017

1.0.3

1.0.3.0

Library for handling hooks.

  Sources   Download

MIT

The Requires

  • php ^5.6 || ^7.0

 

by Avatar Josantonius

hook php hhvm actions action hooks

20/05 2017

1.0.2

1.0.2.0

Library for handling hooks.

  Sources   Download

MIT

The Requires

  • php ^5.6 || ^7.0

 

by Avatar Josantonius

hook php

19/05 2017

1.0.1

1.0.1.0

Library for handling hooks.

  Sources   Download

MIT

The Requires

  • php ^5.6 || ^7.0

 

by Avatar Josantonius

hook php

16/03 2017

1.0.0

1.0.0.0

Library for handling hooks.

  Sources   Download

MIT

The Requires

  • php >=5.6

 

by Avatar Josantonius

hook php