PHP应用的钩子系统

0.0.1 2024-02-10 16:36 UTC

This package is auto-updated.

Last update: 2024-09-10 17:49:58 UTC


README

Hook是一个PHP项目的钩子系统。该项目是从一个很久以前的一个分支分支分支的分支中衍生出来的,现在为了传承而重新启动。

安装

composer require lotharthesavior/hook

上下文

钩子是一种代码片段与另一代码片段交互/修改的方式。它们是在应用程序中特定点执行代码的方式。这是一个非常强大的概念,并被广泛应用于许多应用程序中,包括WordPress,允许开发者在修改核心代码的情况下修改应用程序的行为。

使用钩子的定制点通常被称为"动作"和"过滤器"。动作是代码中发生事情的位置,过滤器是代码中修改位置。例如,在WordPress中,wp_head动作是在输出HTML的<head>部分的位置,而the_content过滤器是在输出内容之前修改内容的位置。

此类是原始PHP Hooks的一个分支的分支的分支的重写,原始PHP Hooks由John Kolbert创建。原始类是为了在WordPress插件和主题中使用而设计的,但此类可用于任何PHP项目。

使用方法

过滤器

过滤器是在执行过程中,在执行某些操作之前(例如将其添加到数据库或写入输出缓冲区 - 终端或浏览器)通过应用程序传递数据的函数。例如,WordPress中的大多数输入和输出都至少通过一个过滤器。过滤器钩子是允许其他开发人员修改或扩展任何代码默认行为的一种很好的方式。

现在,在您的应用程序的任何地方,都可以执行该过滤器

<?php
use Hook\Filter;

Filter::addFilter('filter_name','filter_function');

function filter_function($content){
   return $content.'this came from a hooked function';
}

现在,在您的应用程序的任何地方,都可以执行该动作

<?php

use Hook\Filter;

echo Filter::applyFilters('filter_name','this is the content: ');

动作

动作是在执行过程中或在特定事件发生时应用程序执行函数。动作是在不修改代码的情况下在特定点使应用程序执行某事的方式。在某种意义上,它类似于事件监听器,但名称不同。

现在,在您的应用程序的任何地方,都可以执行该动作

<?php
use Hook\Action;

Action::addAction('header_action','echo_this_in_header');

function echo_this_in_header(){
   echo 'this came from a hooked function';
}

输出将是:<div id="extra_header">this came from a hooked function</div>

<?php

use Hooks\Action;

echo '<div id="extra_header">';
Action::doAction('header_action');
echo '</div>';

方法

短代码

过滤器

/**
 * Adds Hooks to a function or method to a specific filter action.
 *
 * @param string $tag The name of the filter to hook the {@link $functionToAdd} to.
 *
 * @param callable $functionToAdd The name of the function to be called when the filter is applied.
 *
 * @param int $priority [optional] Used to specify the order in
 *                      which the functions associated with a
 *                      particular action are executed (default: 50).
 *                      Lower numbers correspond with earlier execution,
 *                      and functions with the same priority are executed
 *                      in the order in which they were added to the action.
 *
 * @param ?string $includePath [optional] File to include before executing the callback.
 *
 * @return bool
 */
public static function addFilter(
    string $tag,
    callable $functionToAdd,
    int $priority = Hook\Constants::PRIORITY_NEUTRAL,
    ?string $includePath = null,
): bool

/**
 * Call the functions added to a filter hook.
 *
 * INFO: Additional variables passed to the functions hooked to $tag.
 *
 * @param string $tag The name of the filter hook.
 * @param mixed $value The value on which the filters hooked to $tag are applied on.
 *
 * @return mixed The filtered value after all hooked functions are applied to it.
 */
public static function applyFilters(string $tag, mixed $value): mixed

/**
 * Check if any filter has been registered for the given hook.
 * INFO: Use !== false to check if it's true!
 *
 * @param string $tag The name of the filter hook.
 * @param false|callable $function_to_check [optional] Callback function name to check for
 *
 * @return string|int|bool If {@link $function_to_check} is omitted,
 *         returns boolean for whether the hook has
 *         anything registered.
 *         When checking a specific function, the priority
 *         of that hook is returned, or false if the
 *         function is not attached.
 *         When using the {@link $function_to_check} argument,
 *         this function may return a non-boolean value that
 *         evaluates to false (e.g.) 0, so use the === operator for testing the return value.
 *
 */
public static function hasFilter(string $tag, false|callable $function_to_check = false): string|int|bool

/**
 * Removes a function from a specified filter hook.
 *
 * @param string $tag The filter hook to which the function to be removed is hooked.
 * @param callable $functionToRemove The name of the function which should be removed.
 * @param int $priority [optional] The priority of the function (default: 50).
 *
 * @return bool
 */
public static function removeFilter(
    string $tag,
    callable $functionToRemove,
    int $priority = Hook\Constants::PRIORITY_NEUTRAL,
): bool

动作

/**
 * Hooks a function on to a specific action.
 *
 * @param string $tag The name of the action to which the
 *                    $functionToAdd is hooked.
 * @param callable $functionToAdd The name of the function you wish to be called.
 * @param int $priority [optional] Used to specify the order in which
 *                      the functions associated with a particular
 *                      action are executed (default: 50).
 *                      Lower numbers correspond with earlier execution,
 *                      and functions with the same priority are executed
 *                      in the order in which they were added to the action.
 * @param ?string $includePath [optional] File to include before executing the callback.
 *
 * @return bool
 */
public static function addAction(
    string $tag,
    callable $functionToAdd,
    int $priority = Hook\Constants::PRIORITY_NEUTRAL,
    ?string $includePath = null
): bool

/**
 * Execute functions hooked on a specific action hook.
 *
 * @param string $tag The name of the action to be executed.
 * @param mixed $arg [optional] Additional arguments which are passed on
 *                   to the functions hooked to the action.
 * @return bool Will return false if $tag does not exist in $filter array.
 */
public static function doAction(string $tag, mixed $arg = ''): bool

/**
 * Check if any action has been registered for a hook.
 *
 * INFO: Use !== false to check if it's true!
 *
 * @param string $tag The name of the action hook.
 * @param false|string $function_to_check [optional]
 *
 * @return string|int|bool If $function_to_check is omitted,
 *                         returns boolean for whether the hook has
 *                         anything registered.
 *                         When checking a specific function,
 *                         the priority of that hook is returned,
 *                         or false if the function is not attached.
 *                         When using the $function_to_check
 *                         argument, this function may return a non-boolean
 *                         value that evaluates to false (e.g.) 0,
 *                         so use the === operator for testing the return value.
 */
public static function hasAction(
    string $tag,
    false|string $function_to_check = false
): string|int|bool

/**
 * Removes a function from a specified action hook.
 *
 * @param string $tag The action hook to which the function to be removed is hooked.
 * @param callable $functionToRemove The name of the function which should be removed.
 * @param int $priority [optional] The priority of the function (default: 50).
 *
 * @return bool Whether the function is removed.
 */
public static function removeAction(
    string $tag,
    callable $functionToRemove,
    int $priority = Hook\Constants::PRIORITY_NEUTRAL
): bool

许可证

/**
 * Add hook for shortcode tag.
 *
 * There can only be one hook for each shortcode. Which means that if another
 * plugin has a similar shortcode, it will override yours or yours will override
 * theirs depending on which order the plugins are included and/or ran.
 *
 * Simplest example of a shortcode tag using the API:
 *
 * // [footag foo="bar"]
 * function footag_func($attrs) {
 *  return "foo = {$attrs[foo]}";
 * }
 * addShortcode('footag', 'footag_func');
 *
 * Example with nice attribute defaults:
 *
 * // [bartag foo="bar"]
 * function bartag_func($attrs) {
 *  $args = shortcodeAttrs(array(
 *    'foo' => 'no foo',
 *    'baz' => 'default baz',
 *  ), $attrs);
 *
 *  return "foo = {$args['foo']}";
 * }
 * addShortcode('bartag', 'bartag_func');
 *
 * Example with enclosed content:
 *
 * // [baztag]content[/baztag]
 * function baztag_func($attrs, $content='') {
 *  return "content = $content";
 * }
 * addShortcode('baztag', 'baztag_func');
 *
 * @param string $tag Shortcode tag to be searched in post content.
 * @param callable $function Hook to run when shortcode is found.
 *
 * @return bool
 */
public static function addShortcode(string $tag, callable $function): bool

/**
 * Search content for shortcodes and filter shortcodes through their hooks.
 *
 * If there are no shortcode tags defined, then the content will be returned
 * without any filtering. This might cause issues when plugins are disabled but
 * the shortcode will still show up in the post or content.
 *
 * @param string $content Content to search for shortcodes.
 *
 * @return string Content with shortcodes filtered out.
 */
public static function doShortcode(string $content): string

/**
 * Whether the passed content contains the specified shortcode.
 *
 * @param string $content
 * @param string $tag
 *
 * @return bool
 */
public static function hasShortcode(string $content, string $tag): bool

/**
 * Removes hook for shortcode.
 *
 * @param string $tag shortcode tag to remove hook for.
 *
 * @return bool
 */
public static function removeShortcode(string $tag): bool

版权信息

由于此类是从WordPress插件API派生出来的,因此许可证也是一样的,它们是GPL https://gnu.ac.cn/licenses/gpl.html

鸣谢