README

brandon14/fossabot-commander

brandon14/fossabot-commander 的源代码 https://github.com/brandon14/fossabot-commander

要求

目的

我创建了这个库，以帮助在 PHP 中响应 Fossabot 的 customapi 请求。如果您正在运行一个 Web 服务器，并希望将 Fossabot customapi 请求发送到该服务器，此包允许您轻松编写命令并运行它们以返回聊天消息中显示的文本。命令返回字符串的原因是因为 Fossabot 丢弃任何状态码和其他 HTTP 响应内容，只使用原始响应体，这是一个字符串。这个字符串可以是 JSON、文本等。

Fossabot 的 customapi 的常规用法可能如下所示

将命令 !foo 设置为 $(customapi https://foo.bar/foo)。

当有人输入 !foo 时，Fossabot 将向 https://foo.bar/foo 发送请求，并使用该 URL 返回的内容作为聊天消息。使用此包，您可以轻松创建命令，并通过 FossabotCommander::runCommand() 方法调用它们，并在您选择的 Web 框架中使用这些实用程序。

此库使用请求验证端点验证 Fossabot 请求，因此您可以确保请求来自 Fossabot。您还可以选择（默认启用）获取有关请求的更多上下文，如此处所述，以提供更丰富的 Fossabot 集成。将 FossabotContext 数据传递到命令的 getResponse 方法。

安装

composer require brandon14/fossabot-commander

用法

您首先需要从请求头中获取自定义 API 令牌。它将在 x-fossabot-customapitoken 头中。

对于简单的命令（以 Laravel 作为示例 Web 框架）

// FooCommand.php
<?php

declare(strict_types=1);

namespace App\Fossabot\Commands;

use Brandon14\FossabotCommander\FossabotCommand;
use Brandon14\FossabotCommander\Contracts\Context\FossabotContext;

class FooCommand extends FossabotCommand
{
    /**
     * {@inheritDoc}
     */
    public function getResponse(?FossabotContext $context = null) : string
    {
        return 'Hello chat!';
    }
}

// In some Laravel Controller
<?php

declare(strict_types=1);

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use App\Fossabot\Commands\FooCommand;
use Illuminate\Routing\Controller as BaseController;
use Illuminate\Foundation\Validation\ValidatesRequests;
use Illuminate\Foundation\Auth\Access\AuthorizesRequests;
use Brandon14\FossabotCommander\Contracts\FossabotCommander;

class Controller extends BaseController
{
    use AuthorizesRequests;
    use ValidatesRequests;

    private FossabotCommander $commander;

    public function __construct(FossabotCommander $commander)
    {
        $this->commander = $commander;
    }
    
    public function fooCommand(Request $request): string
    {
        // Get Fossabot API token.
        $apiToken = $request->header('x-fossabot-customapitoken');

        // Invoke command.
        return $this->commander->runCommand(new FooCommand(), $apiToken);
    }
}

您也可以向 runCommand() 提供一个可调用的函数，而不是 FossabotCommand 的实例，前提是这个可调用的函数返回一个字符串，并接受一个可选的 FossabotContext|null 参数。

// In some Laravel Controller
<?php

declare(strict_types=1);

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use App\Fossabot\Commands\FooCommand;
use Illuminate\Routing\Controller as BaseController;
use Illuminate\Foundation\Validation\ValidatesRequests;
use Illuminate\Foundation\Auth\Access\AuthorizesRequests;
use Brandon14\FossabotCommander\Contracts\FossabotCommander;
use Brandon14\FossabotCommander\Contracts\Context\FossabotContext;

class Controller extends BaseController
{
    use AuthorizesRequests;
    use ValidatesRequests;

    private FossabotCommander $commander;

    public function __construct(FossabotCommander $commander)
    {
        $this->commander = $commander;
    }
    
    public function fooCommand(Request $request): string
    {
        // Get Fossabot API token.
        $apiToken = $request->header('x-fossabot-customapitoken');
        
        $command = function(?FossabotContext $context = null): string {
            return 'Hello chat!';
        }

        // Invoke command.
        return $this->commander->runCommand($command, $apiToken);
    }
}

这为您提供了一种更易于实现的方法来创建快速命令，这些命令不需要很多外部依赖项，或者是一种更便携的方法来发送 Fossabot 消息。

FossabotCommander 类需要一个 PSR 兼容的 ClientInterface 和一个 PSR 兼容的 RequestFactoryInterface。这些可以由像 guzzlehttp/guzzle 或其他 PSR 兼容的库提供。在上面的 Laravel 示例中，我们假设 Laravel 容器已将 FossabotCommander 实例绑定到容器中。

对于更复杂的命令，天高任鸟飞。根据您想要构建和实例化您的 FossabotCommand 实例的方式，您可以使用 FossabotContext 数据来为您的 Fossabot 聊天机器人提供丰富的集成！

Laravel 中的使用

如果您计划在 Laravel 项目中使用 fossabot-commander，请查看我制作的用于在 Laravel 生态系统内轻松集成的 Laravel 扩展包 fossabot-commander-laravel。

标准

我们努力遵守 PHP 项目的 PSR-12 编码风格，并通过 php-cs-fixer 检查工具强制执行我们的编码标准。我们的规则集可以在 .php-cs-fixer.dist.php 文件中找到。

覆盖率

最新的代码覆盖率信息可以通过 Codecov 查找。我们努力保持整个库的 100% 覆盖率，因此如果您正在贡献，请确保包含对新代码添加的测试。

文档

该项目的文档可以在此处找到。

贡献

有什么要添加的吗？发现了错误或代码有问题？请随意提交拉取请求以添加新功能、修复错误或整理代码。只需确保遵循行为准则和贡献指南，如果可能的话，我们鼓励创建干净且描述良好的拉取请求。

如果您注意到库中的问题或想建议新功能，请随意使用问题跟踪器合适地创建问题。

为了运行测试，建议您注册 Cloudinary 账户（这是一个免费服务），并使用该账户运行完整的集成测试。为了做到这一点，您需要将 .env.example 复制到 .env 并使用账户详情填写变量。集成测试将使用随机前缀目录，并在测试前后清理一切。

版本控制

brandon14/fossabot-commander 使用类似于 MAJOR.MINOR.PATCH 的语义版本控制。

主版本变更将包括不兼容的更改，可能需要使用它的项目的重构。次要版本变更将包括向后兼容的新功能和更改，不会破坏现有用法。补丁版本变更将包括向后兼容的错误和安全修复，应尽快更新。

安全漏洞

如果您在此软件包中发现漏洞，请通过 brandon14125@gmail.com 发送电子邮件给 Brandon Clothier。所有安全漏洞都将得到及时处理。

此代码根据 MIT 许可证发布。

brandon14 / fossabot-commander

维护者

详细信息