README

这是现在已不活跃的 esemve/Hook 库为 Laravel 8 的维护分支。

在大多数情况下，这个库可以作为直接替换使用，尽管可能需要对您的代码进行一些小的更新。请参阅 差异部分 以获取有关此库与 esemve/Hook 之间变化的更多信息

这是什么？

钩子允许程序员将应用程序的某些部分开放给其他代码库中的修改或调整。例如，允许应用程序修改包的行为，而无需直接编辑其源代码。

什么是钩子？

它类似于事件。除非钩子监听器捕获它并命令执行钩子中的其他函数，否则被钩子包围的代码将运行。它们可以按既定顺序设置，因此您可以在代码中进行多项修改。

它有什么好处？

示例 1：您有一个显示编辑器的模块。在所有情况下，它都使用相同的编辑器。如果将编辑器的显示绑定到钩子上，则可以编写一个模块来重新定义/覆盖此钩子，例如将文本区域更改为 ckeditor。

示例 2：您列出用户。您可以在钩子中包含每行的打印。这样，您可以编写一个独立的模块，可以扩展此行以打印电子邮件地址。

示例 3：您将用户数据保存到数据库中。如果在钩子中这样做，则可以编写一个模块，可以在用户模型中添加额外字段，例如“名字”或“姓氏”。为此，您不需要修改处理用户的代码，扩展模块不需要知道主模块的功能。

... 以及许多其他事情。如果您正在构建类似 CMS 的系统，这将使您的生活变得更加轻松。

如何安装它？

composer require coinvestor/larahook

它是如何工作的？

示例代码

$user = new User();
$user = Hook::get('fillUser', [$user], function($user) {
    return $user;
}, true);

在这种情况下，抛出了一个 fillUser 钩子，该钩子接收 $user 对象作为参数。如果没有监听器捕获它，则将运行内部函数，返回 $user，因此不会发生任何事情。但它可以被提供者的监听器捕获

Hook::listen('fillUser', function ($callback, $output, $user) {
    $output->profileImage = ProfileImage::getForUser($user->id);
    return $output;
}, 10);

$callback 包含钩子的原始内部函数，因此可以在此处调用它。

可以为钩子注册多个监听器，因此监听器在 $output 中接收先前注册的钩子监听器的响应。

然后是钩子传递的参数，在这种情况下是用户。

上面的钩子监听器捕获了 fillUser 的调用，扩展了接收到的对象，并将其返回到其原始位置。在钩子运行后，$user 对象将包含一个 profileImage 变量。

示例中的第 10 个数字是优先级。它们按顺序执行，因此如果将编号 5 也注册到 fillUser，则它将在编号 10 之前运行。

方法

获取

运行钩子并返回一些数据。将触发钩子的监听器，并将这些结果的最终结果返回。

Hook::get(
    string $hook,                    // Name of the hook to run
    array $params,                   // Array of values to be passed to the listeners on this hook.
    callable $callback,              // Callback method to return default value if no listeners are registered.
    bool $useCallbackAsFirstListener // Should the default callback be run and used as the first $output value
                                     // for the listeners. Defaults to false.
);

监听

监听钩子并执行操作或操纵输出，然后返回。

Hook::listen(
    string $hook,            // Name of the hook to listen on.
    callable $method (       // Callback to execute when hook is run. 
        callable $callback,  // Default callback from the `get`. Called as `$callback->call` 
        mixed $output,       // Output from previous hook. Will be null unless useCallbackAsFirstListener
                             // is set to true, in which case it will be the default callbacks value.
        mixed $arg1,         // Each value provided to the `get` methods params array, is added to the
        mixed $arg2,         // callbacks arguments in the order they were added.
    )
    int $priority            // Used the control when each listener runs. The higher this value, the later it will run in the list of listeners on the hook.
);

初始输出

通过将 true 作为 get 方法的第 4 个参数传递，您可以确保默认回调始终运行，并传递其自身作为初始输出值。

Hook::get('testing', ['Delilah'], function ($testString) {
    return 'Hi ' . $testString;
}, true)

// and later ...

Hook::listen('testing', function ($callback, $output, $name) {
    if ($output === 'Hi Delilah') {
        $output = "{$output}. Whats up!";
    } else {
        $output = "{$output}. Welcome back.";
    }
    return $output; // 'Hi Delilah. Whats up!'
});

如果没有监听器，将返回 'Hi Delilah'。

在 blade 模板中的使用

@hook('hookName')

在这种情况下，钩子监听器可以像这样捕获它

 Hook::listen('template.hookName', function ($callback, $output, $variables) {
     return view('test.button');
 });

在 $variables 变量中，它接收所有可用于 blade 模板的变量。

❗ 要监听 blade 模板，您需要监听 template.hookName 而不是仅仅 hookName！

包装 HTML

@hook('hookName', true)
    this content can be modified with dom parsers
    you can inject some html here
@endhook

现在 $output 参数包含由钩子组件包装的 HTML。

Hook::listen('template.hookName', function ($callback, $output, $variables) {
    return "<div class=\"alert alert-success\">$output</div>";
});

停止

Hook::stop();

放入钩子监听器中，它将停止运行注册到该钩子上的其他监听器。

用于测试

Hook::mock('hookName','returnValue');

之后，hookName 钩子将返回 returnValue 作为响应。

Artisan

php artisan hook::list

列出所有活动的钩子监听器。

与 esemve/Hook 之间的区别

• 在 Hook::get 上的 $InitialContent 参数已被 useCallbackAsFirstListener 标志所取代。将此设置为 true 将返回默认回调的结果作为初始的 $output 值。
• 同一钩子上的同一优先级的监听器将不再覆盖彼此。同一优先级的监听器将按照您注册它们的顺序运行。
• 从监听器返回一个假值现在将直接返回该值，而不是导致返回默认回调。
• 与 Laravel 8+ 兼容。
• getListeners 现在可以返回指定钩子的监听器。结果始终是一个数组。
• 调用者信息现在包括文件名和行号。
• 添加了 removeListener 和 removeListeners 方法。

许可证：MIT