slack-php / slick
用于 Slack 应用开发的简单微框架
1.0.0
2021-06-10 01:45 UTC
Requires
- php: >=7.3
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.0
- kahlan/kahlan: ^5.1
- phpstan/phpstan: ^0.12.89
README
A slick, single-file, dependency-free PHP micro-framework for building simple Slack apps.
如果您需要更强大的功能,请使用我们完全功能的 Slack PHP 框架。
如果您是 Slack 应用开发的初学者,您可以在 Slack 网站 上了解相关信息。
安装
要求
需要 PHP 7.3+ 并支持 JSON。
通过 Composer
我们建议使用 Composer 安装 Slick,这样自动加载和更新就变得简单。
composer require slack-php/slick
手动
然而,由于 Slick 没有依赖项,您可以直接下载并 require Slick.php
,或者直接将代码复制粘贴到您的项目中。
(如果您最终这样做,请告诉我,因为这将是我唯一能够跟踪这种情况的方式。)
基本用法
这个小程序通过回复 /cool
命令,在 Slack 命令被使用的对话中发送一条消息。
假设
- 您已 require Composer 的自动加载器来自动加载 Slick,或者您已直接 require
Slick.php
。- 您已设置
SLACK_SIGNING_KEY
到您的环境中,使其存在于$_SERVER
中。
<?php SlackPhp\Slick::app() ->route('command', '/cool', function (array $payload) { return "Thanks for running the `{$payload['command']}` command. You are cool! :thumbsup:"; }) ->run();
想在自己的工作空间中运行此示例?请查看使用 Docker 的 示例应用。
分解
让我们在最后一个示例中添加一些注释,以便您知道正在发生什么。
<?php // Create the Slick app object. SlackPhp\Slick::app() // Add a routable listener to the app to handle logic for a specific interaction. ->route( // The payload type (e.g., command, block_actions, view_submission, shortcut, and others). 'command', // The payload ID. It's different based on the type. For commands, it is the command name. '/cool', // The listener that handles the specific interaction's logic. function (array $payload) { // Any app logic can be done here, including calling Slack's APIs. // Whatever you do, it should take less than 3 seconds, so you can "ack" before Slack's timeout. // Whatever is returned will be included as part of the "ack" (response) body. You can return a string, an // associative array, or JSON-serializable object. You should make sure that anything you include in the ack // is supported by the type of interaction you are responding to. Many interactions don't require an ack // body, so you can also return null, and empty string, or just omit a return statement, entirely. return "Thanks for running the `{$payload['command']}` command. You are cool! :thumbsup:"; } ) // Add as many routes as you need to handle all your interactions. ->route(...) ->route(...) ->route(...) // Runs the Slack app. This includes the following steps: // 1. Reads data from the current request (e.g., via $_SERVER and php://input). // 2. Validates the request from Slack, including verifying the request signature from the header. // 3. Parses the request body into an array of Slack payload data. // 4. Determines the payload type and ID. // 5. Executes one of the registered listeners based on the payload type and ID. // 6. Acks (responds) back to Slack. ->run();
自定义
没有太多可以自定义的,但您可以在以下情况下控制您的 Slick Slack 应用的行为:
- 传入的请求不匹配您的任何路由(
on404()
)。 - 处理传入请求时发生错误(
orErr()
)。
<?php SlackPhp\Slick::app() ->route(...) ->route(...) ->route(...) ->on404(function (array $payload) { // Do something custom. This is essentially used as a catch-all listener. // If you don't use on404(), then your app throws an error. }) ->onErr(function (Throwable $err) { // Do something custom. // If you don't use onErr(), then your app calls `error_log()` and acks with a 500-level response. }) ->run();
辅助函数
如果您想自己处理请求,Slick 提供了一些静态辅助方法,您可以使用它们独立于路由功能。
Slick::validateSignature(string $key, string $signature, int $time, string $body): void
– 使用 v0 算法验证 Slack 请求签名。Slick::parseRequestBody(string $body): array
– 将请求体解析为 Slack 有效载荷数据的关联数组。适用于任何有效载荷类型。必须提供原始请求体作为字符串(例如,来自php://input
)。Slick::getPayloadType(array $payload): string
– 从有效载荷数据数组中确定有效载荷类型。Slick::getPayloadId(array $payload): string
– 根据类型,从有效载荷数据数组中确定有效载荷的可路由 ID。Slack::ack(string $ack): void
– 输出带有适当头和状态码的 "ack" 响应。