README

翻译: 西班牙语

PHP 中处理钩子的库。

• 需求
• 安装
• 可用类
  • 动作实例
  • 钩子类
  • 优先级类
• 使用的异常
• 用法
• 测试
• 待办事项
• 变更日志
• 贡献
• 赞助
• 许可

需求

• 操作系统: Linux | Windows。

• PHP 版本: 8.1 | 8.2。

安装

通过 Composer 安装此扩展是首选方式。

要安装 PHP 钩子库，只需

composer require josantonius/hook

上述命令只会安装必要的文件，如果您想 下载整个源代码，可以使用

composer require josantonius/hook --prefer-source

您也可以使用 Git 克隆完整仓库

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

可用类

动作实例

Josantonius\Hook\Action

获取动作优先级

public function getPriority(): int;

获取动作回调结果

public function getResult(): mixed;

检查动作是否只执行一次

public function isOnce(): bool;

检查动作是否已经执行

public function wasDone(): bool;

钩子类

Josantonius\Hook\Hook

注册新钩子

public function __construct(private string $name);

在钩子上添加动作

/**
 * Action will be maintained after performing actions and will be available if are done again.
 * 
 * @see https://php.ac.cn/manual/en/functions.first_class_callable_syntax.php
 * 
 * @return Action Added action.
 */
public function addAction(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 action.
 */
public function addActionOnce(callable $callback, int $priority = Priority::NORMAL): Action;

运行添加到钩子上的动作

/**
 * @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;

检查钩子是否有动作

/**
 * True if the hook has any action even if the action has been
 * done before (recurring actions created with addAction).
 */
public function hasActions(): bool;

检查钩子是否有撤销动作

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

检查动作是否至少执行过一次

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

获取钩子名称

public function getName(): string;

优先级类

Josantonius\Hook\Priority

可用常量

public const HIGHEST = 50;
public const HIGH    = 100;
public const NORMAL  = 150;
public const LOW     = 200;
public const LOWEST  = 250;

使用的异常

use Josantonius\Hook\Exceptions\HookException;

用法

此库的使用示例

注册新钩子

use Josantonius\Hook\Hook;

$hook = new Hook('name');

在钩子上添加动作

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(...));

在钩子上添加具有自定义优先级的动作

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

在钩子上添加一次动作

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(...));

在钩子上添加一次具有自定义优先级的动作

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

以相同优先级执行动作

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();

以不同优先级执行动作

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();

执行带有参数的动作

use Josantonius\Hook\Hook;

function foo($foo, $bar) { /* do something */ }

$hook = new Hook('name');

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

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

重复执行动作

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

只执行一次动作

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

检查钩子是否有动作

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

检查钩子是否有撤销动作

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

检查动作是否至少执行过一次

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

获取钩子名称

use Josantonius\Hook\Hook;

$hook = new Hook('foo');

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

获取动作优先级

use Josantonius\Hook\Hook;

function foo() { /* do something */ }

$hook = new Hook('name');

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

$action->getPriority();

获取动作回调结果

use Josantonius\Hook\Hook;

function foo() { /* do something */ }

$hook = new Hook('name');

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

$action->getResult();

检查动作是否只执行一次

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

检查动作是否已经执行

use Josantonius\Hook\Hook;

function foo() { /* do something */ }

$hook = new Hook('name');

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

$action->wasDone(); // false

$hook->doActions();

$action->wasDone(); // true

测试

要运行 测试，您只需要 composer 并执行以下命令

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

cd php-hook

composer install

使用 PHPUnit 运行单元测试

composer phpunit

使用 PHPCS 运行代码标准测试

composer phpcs

使用 PHP Mess Detector 测试以检测代码风格的冲突

composer phpmd

运行所有之前的测试

composer tests

待办事项

• 添加新功能
• 改进测试
• 改进文档
• 改进 README 文件中的英文翻译
• 重构代码以禁用代码风格规则（见 phpmd.xml 和 phpcs.xml）
• 使 Action->runCallback() 只对 Hook 类可访问
• 添加删除动作的方法？
• 添加在动作中添加 ID 的选项？

变更日志

每个版本的详细更改记录在 发行说明 中。

贡献

请在发起拉取请求、开始讨论或报告问题之前，务必阅读 贡献指南。

感谢所有 贡献者! ❤️

赞助

如果这个项目帮助您减少了开发时间，您可以 赞助我 以支持我的开源工作 😊

许可

本仓库遵循 MIT 许可协议。

版权所有 © 2017-至今，Josantonius