README

描述

此包用于发送 Slack 消息和处理与 Slack 消息的交互：点击消息按钮和通过对话框与用户交互。

安装

通过 composer 安装包

composer require pdffiller/laravel-slack

安装服务提供者

// config/app.php
'providers' => [
    ...
    Pdffiller\LaravelSlack\LaravelSlackServiceProvider::class,
];

发布配置和数据库迁移文件

php artisan vendor:publish --provider="Pdffiller\LaravelSlack\LaravelSlackServiceProvider"

运行迁移

php artisan migrate

这是已发布 laravel-slack-plugin.php 配置文件的正文

return [
    /*
     * Bot User OAuth Access from Slack App
     */
    'bot-token' => env('SLACK_BOT_TOKEN', null),

    /*
     * Verification token from Slack App
     */
    'verification_token' => env('SLACK_VERIFICATION_TOKEN', null),

    /*
     * Handlers are processed by controller
     */
    'handlers' => [
    ],

    /*
     * Endpoint URL
     */
    'endpoint-url' => 'slack/handle'
];

使用方法

发送消息

插件支持 Slack API 中的这些方法

• chat.postMessage
• chat.update
• dialog.open
• files.upload

您可以将服务 Pdffiller\LaravelSlack\Services\LaravelSlackPlugin 注入到您的函数中。

服务有 2 个方法

• buildMessage((AbstractMethodInfo $method), [Model $model], [string $options])
• sendMessage([$message])

这些类的实例可以用作 $method 参数

• Pdffiller\LaravelSlack\AvailableMethods\ChatPostMessage
• Pdffiller\LaravelSlack\AvailableMethods\ChatUpdate
• Pdffiller\LaravelSlack\AvailableMethods\DialogOpen
• Pdffiller\LaravelSlack\AvailableMethods\FilesUpload

Eloquent 模型可以用作非必填的 $body 参数。

通过 chat.postMessage 方法发送的所有 Slack 消息都保存在数据库中的 laravel_slack_message 表中。每个消息都保存 Slack 消息的 ts 和 channel。如果将 Eloquent 模型作为 buildMessage 方法的 $body 参数发送，则还会保存模型的主键和模型路径。如果将 JSON 选项作为 buildMessage 方法的 $options 参数发送，它也将保存在数据库中。然后，您可以使用 ts 和 channel 参数在 chat.update 方法中更新现有的 Slack 消息。

发送纯文本消息

$slack = resolve(\Pdffiller\LaravelSlack\Services\LaravelSlackPlugin::class);
$slack->buildMessage(new \Pdffiller\LaravelSlack\AvailableMethods\ChatPostMessage())
           ->setChannel("#ABCDEF") //channel id from web app
           ->setText("asdsadsad");
$slack->sendMessage();

更新 Slack 消息

$slack = resolve(\Pdffiller\LaravelSlack\Services\LaravelSlackPlugin::class);
slack->buildMessage(new \Pdffiller\LaravelSlack\AvailableMethods\ChatUpdate())
           ->setChannel("#ABCDEF")
           ->setTs('1405894322.002768')
           ->setText("updated text");
$slack->sendMessage();

构建带附件的消息

为了构建带 附件 的消息，插件有这些类

• Pdffiller\LaravelSlack\RequestBody\Json\Attachment
• Pdffiller\LaravelSlack\RequestBody\Json\AttachmentField
• Pdffiller\LaravelSlack\RequestBody\Json\AttachmentAction

发送带文本附件的消息

$slack = resolve(\Pdffiller\LaravelSlack\Services\LaravelSlackPlugin::class);
$slack->buildMessage(new \Pdffiller\LaravelSlack\AvailableMethods\ChatPostMessage())
                   ->setChannel("#ABCDEF")
                   ->addAttachment(\Pdffiller\LaravelSlack\RequestBody\Json\Attachment::create()
                                         ->setText("this is text")
                                         ->setColor('#36a64f')); // default color is #D3D3D3
$slack->sendMessage();

发送包含字段附件的消息

$slack = resolve(\Pdffiller\LaravelSlack\Services\LaravelSlackPlugin::class);
$slack->buildMessage(new \Pdffiller\LaravelSlack\AvailableMethods\ChatPostMessage())
           ->setChannel("#ABCDEF")
           ->addAttachment(\Pdffiller\LaravelSlack\RequestBody\Json\Attachment::create()
                         ->addFields([                  
                                 [                           
                                     'title' => 'User Id',
                                     'value' => 10
                                     /*, 'short'=true/false*/  // short is true by default, it means that next field is shown on the same line
                                 ],
                                 \Pdffiller\LaravelSlack\RequestBody\Json\AttachmentField::create('Team Id', 10),
                             ]
                         ));
$slack->sendMessage();

发送包含操作的附件消息

$slack = resolve(\Pdffiller\LaravelSlack\Services\LaravelSlackPlugin::class);
$slack->buildMessage(new \Pdffiller\LaravelSlack\AvailableMethods\ChatPostMessage())
               ->setChannel("#ABCDEF")
               ->addAttachment(\Pdffiller\LaravelSlack\RequestBody\Json\Attachment::create()
                   ->setCallbackId('callback-id-is-used-in-handler')
                   ->setFallback('Fallback text') // Required plain-text summary of the attachment
                   ->setColor('#36a64f')
                   ->addActions([
                           [
                               'name' => 'button-name',
                               'text' => 'Accept',
                               'value' => 1,
                               /*'style' => 'primary/danger',
                               'type'  => 'button'*/
                           ],
                           \Pdffiller\LaravelSlack\RequestBody\Json\AttachmentAction::create('button-name', 'Decline', 0)
                       ]
                   ));
$slack->sendMessage();

发送 文件

$slack = resolve(\Pdffiller\LaravelSlack\Services\LaravelSlackPlugin::class);
$slack->buildMessage(new \Pdffiller\LaravelSlack\AvailableMethods\FilesUpload())
                ->setChannel("#ABCDEF")
                ->setFilePath("/uploads/one.txt") //path to file in your project or web
                ->setFileName("one.txt); 
$slack->sendMessage();

在消息交互后打开 对话框

在交互消息后（例如点击按钮）可以打开对话框。与消息交互后，请求有效载荷中会发送 trigger_id。此参数用于 dialog.open 方法。

为了构建对话框插件有这些类

• Pdffiller\LaravelSlack\RequestBody\Json\Dialog
• Pdffiller\LaravelSlack\RequestBody\Json\DialogElement

$slack = resolve(\Pdffiller\LaravelSlack\Services\LaravelSlackPlugin::class);
$slack->buildMessage(new \Pdffiller\LaravelSlack\AvailableMethods\DialogOpen())
                   ->setTriggerId('trigger_id')
                   ->setDialog(\Pdffiller\LaravelSlack\RequestBody\Json\Dialog::create()
                           ->setCallbackId('will-be-used-in-handler')
                           ->setTitle('Title')
                           ->setSubmitLabel('Save')
                           //->setState(json_encode([])) // you can save some data between opening dialog and handling                                                                   it's interaction in the state parameter
                           ->addElement(\Pdffiller\LaravelSlack\RequestBody\Json\DialogElement::create()
                                             ->setName('reason')
                                             ->setLabel('...')
                                             ->setType(DialogElement::TEXTAREA_TYPE))
                   );
$slack->sendMessage();

处理交互组件

插件支持处理按钮和对话框的交互。所有来自 Slack 的请求都发送到插件的端点。可以在生成的 laravel-slack-plugin.php 配置文件中的 endpoint-url 部分更改此 URL。应在您的 Slack 应用程序中的 Interactive Components 部分添加此 URL。应在您的配置文件中添加 Slack 应用的 OAuth 访问令牌和验证令牌。

插件有方便的处理程序系统，用于处理所有交互。附件和对话框都有 callback_id 参数。与按钮或对话框的每次交互后，Slack 都会将请求发送到 /slack/handle 端点。请求有效载荷中包含 callback_id 参数，因此可以通过此参数区分所有请求。因此，应针对每种 callback_id 类型的请求实现一个处理程序。

插件包含一个Pdffiller\LaravelSlack\Handlers\BaseHandler类，该类具有以下方法

• shouldBeHandled()
• handle()

在您的项目中，您应该在插件的BaseHandler类之上实现您自己的处理器。

处理器示例

use Pdffiller\LaravelSlack\Handlers\BaseHandler;

class CustomHandler extends BaseHandler
{    
    // check if this handler should be executed
    public function shouldBeHandled()
    {
        $payload = json_decode($this->request->get('payload'), true);
        $callBackId = Arr::get($payload, 'callback_id');

        return $callBackId === 'some-callback-id';
    }
    
    public function handle()
    {
        $payload = json_decode($this->request->get('payload'), true);
        // ...
    }
}

将处理器添加到项目生成的laravel-slack-plugin.php配置文件中的handlers部分。

'handlers' => [
        \App\Slack\Handlers\CustomHandler::class,
        ...
]