README

这个库的作用是什么

它允许轻松处理AmoCRM的WebHooks，无需编写大量检查钩子实体和事件的逻辑以及请求体中的各种变量。只需专注于处理，并将数据处理任务委托给这个类。

安装

composer require opravdin/amohook

使用

在AmoCRM中为你的钩子设置入口点（处理器的URL）。可以选择只处理必要的事件或全部事件。

方法 1. 使用调用链

设置Webhook处理流程。注册3种类型的处理器

直接处理器 - 适合处理逻辑
错误处理器 - 当第一个组处理完成后抛出异常时调用。可以中断后续处理器的执行。
最终处理器 - 当第一个组的每个处理器完成时启动。接收输入参数

use Opravdin\AmoHook\AmoHook;
// Удобно подключить константы с событиями и сущностями:
use Opravdin\AmoHook\Events;
use Opravdin\AmoHook\Entities;

// Для Laravel удобнее применить $request->all() вместо $_POST
AmoHook::build($_POST) 
    ->register('any', 'any', function ($payload) {
        // Вызовется для любой сущности при любом событии, подходит для отладки и логгирования приходящих данных
        Log::debug("Action: {$payload['action']} on entity {$payload['entity']}");
    })
    ->register(
        ['contacts', 'companies'], ['update', 'add'], function ($payload) {
        /**
         * Вызывается только для контактов и компаний при обновлении и добавлении
         * Для register первые 2 параметра могут быть как строками, так и наборами строк. 
         * При этом обработчик будет выполнен если произойдет любое из указанных события с любой указанной сущностью
         */
    })
    ->register([Entities::COMPANY, Entities::CONTACT], [Events::ADD, Events::UPDATE], function ($payload) {
        // Этот обработчик запустится при тех же условиях, что и предыдущий
    })

    // Можно подключить методы для обработки ошибок (один или несколько)
    ->onError(function ($exception, $payload, $entity, $action) {
        // Этот код выполнится при возникновении исключения при обработке
        Log::error("Произошла ошибка при обработке хука: ".$exception->getMessage());

        /**
         * $exception - возникшее исключение
         * $payload - данные, аналогичные передаваемым в обработчик
         * $entity, $action - сущность и событие, в контексте которых выполнялась обработка хука
         */

        // Завершить выполнение обработчиков (вернуть значение === true)
        // Все остальные onError все еще будут выполнены, а также after
        // Другие onError не смогут предотвратить отмену работы остальных обработчиков
        return true;

        // Продолжить выполнение других обработчиков (любое значение !== true)
        return false; 
    })

    // Выполнить после каждого обработчика (можно несколько)
    ->after(function ($result, $payload) {
        // $result - результаты работы
        // $payload - событие, по которому была работа
    })
    // Запустить цепочку
    ->handle();

使用数组注册多个操作/实体，或传递字符串以进行选择性注册。该方法将事件作为调用参数接收。

传递给处理器的$payload内容

entity - 与AmoCRM钩子对应的实体名称（公司除外，它们被视为companies）
action - 事件名称（例如，add或update）
data - 事件体。包括钩子中该事件的所有数据（id，name等）。相当于$request['实体']['事件'][0]

[
    'entity' => 'contacts', 
    'action' => 'update',
    'data' => [
        // Содержимое хука, например
        'id' => 123, 
        'name' => 'Иван Иванов',
        // ...и так далее
    ]
]

方法 2. 简化数据获取

最简单的方法：获取具有特定实体和事件类型的处理后的数组数据。数组包含与上面方法中的$payload类似的实体

use Opravdin\AmoHook\AmoHook;

// Использование без фреймворков
$raw = $_POST;
$data = (new AmoHook($_POST))->get();
foreach ($data as $event) {
    echo "Action: {$data['action']} on entity {$data['entity']}";
}

// Или через build
$raw = $_POST;
$data = AmoHook::build($raw)->get();

// Использование с Laravel Request
$content = $request->all();
$data = AmoHook::build($content)->get();

你可以查看测试（tests）来了解类的工作原理

错误处理和调试

默认情况下，类会隐藏错误处理器中的所有操作，因为amoCRM在短时间内错误数量超过特定阈值时将禁用WebHooks。因此，为了跟踪错误和调试，强烈建议至少添加一个onError日志记录处理器。或者，可以通过在handle()之前调用setErrorThrowing(true)强制库输出错误。

跟踪处理器运行时间

当amoCRM运行时，它期望服务器在最多2秒内提供响应。从amoCRM的角度来看，长时间的响应等同于错误的返回码，这也会导致禁用钩子。可以使用以下结构来测量时间：

$time = -microtime(true);
// Логика обработки хуков
// AmoHook::build(...)->...->handle();
$time += microtime(true);
if ($time >= 1.5) {
    Log::warning("Обработка хука заняла более 1.5 секунд! ".$time);
}
// return ответ с кодом 200

注意：这种测量方法并不完全准确，因为它不考虑实际处理请求的开始时间，请参阅链接

可用的实体和事件

所有实体和事件都按照它们在Webhooks AmoCRM中的名称命名（例如，leads，contacts和update，add等）。值得注意的是，库正确地区分了联系人和公司：contacts和companies。此外，可以使用any来为回叫方法定义实体和事件。
为了简化工作，所有实体和事件的名称都已提取出来

贡献

我非常愿意接受你在Issues或Pull requests中的评论、建议和改进 :)

opravdin/amohook

维护者

详细信息