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 应用的行为：

1. 传入的请求不匹配您的任何路由（on404()）。
2. 处理传入请求时发生错误（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" 响应。