README

为 快手小程序(Kuaishou Mini Program) 平台打造的服务端 SDK,专为 Laravel 设计。

功能特性

access_token 管理 —— 缓存 + 惰性刷新,48 小时有效期。与部分平台不同,快手重复获取新 token 不会让旧 token 立即失效,因此无需防踩踏锁。
code2Session 登录 —— 用 ks.login 下发的 js_code 换取 session_key / open_id。
小程序二维码 —— 返回 base64 图片字符串(并提供解码后的二进制辅助方法),支持尺寸/颜色/logo 配置。
订阅消息 —— 向已订阅用户发送模板消息(平台限制 QPS 100)。
Webhook 回调 —— 验证事件推送签名(kwaisign 头,全文 MD5 + app_secret),并按 message_id 原子去重(平台在未收到 {"result": 1} 前最多重推 16 次)。

环境要求

PHP 8.5
Laravel 13.x

安装

composer require fengz/kuaishou-miniapp-sdk

发布配置文件:

php artisan vendor:publish --tag=kuaishou-miniapp-config

在 .env 中配置凭证:

KUAISHOU_MINIAPP_APP_ID=your-app-id
KUAISHOU_MINIAPP_APP_SECRET=your-app-secret

使用

use Fengz\KuaishouMiniapp\Facades\KuaishouMiniapp;

// code2Session 登录(前端调用 ks.login() → 把 js_code 发到你的服务器)
$session = KuaishouMiniapp::auth()->session($jsCode);
// ['result' => 1, 'session_key' => ..., 'open_id' => ...]

// 生成小程序二维码(base64 字符串)
$base64 = KuaishouMiniapp::qrcode()->generateBase64(['path' => 'pages/index/index', 'width' => 430]);
// 或解码后的二进制字节
$binary = KuaishouMiniapp::qrcode()->generateBinary(['path' => 'pages/index/index']);
// 或两者一起返回
$result = KuaishouMiniapp::qrcode()->generate();
// ['base64' => ..., 'binary' => ...]

// 订阅消息
KuaishouMiniapp::subscribe()->send(
    templateId: 'tpl-xxx',
    toUser: 'openid-xxx',
    page: 'pages/index/index',
    data: ['thing' => ['value' => '苹果']],
);

// Webhook 回调:验签 → 去重 → 应答
if (! KuaishouMiniapp::callback()->verifyRequest($request)) {
    abort(403); // kwaisign 签名不合法(rawBody . app_secret 的 md5)
}

$messageId = KuaishouMiniapp::callback()->messageIdFromRequest($request);

// 平台会用同一个 message_id 重推(最多 16 次),直到收到 {"result": 1}
// —— 只有首次送达才处理。
if ($messageId === null || KuaishouMiniapp::callback()->dedupe($messageId)) {
    $payload = json_decode((string) $request->getContent(), true);
    // 按 $payload['biz_type'] 处理 $payload['data']
}

return response()->json(['result' => 1, 'message_id' => $messageId]);

也可以通过全局辅助函数调用:

$session = kuaishou_miniapp()->auth()->session($jsCode);

关于成功码

快手网关用 result 作为成功/失败标记,但成功值在各接口间并不统一:

接口	成功 `result`
getAccessToken、code2Session、sendMessage	`1`
generateMpQrCode	`0`

HTTP 客户端支持按调用传入成功码(默认 1),二维码管理器内部已显式传 0。你无需关心这个差异——每个管理器都会走正确的值。

错误处理

SDK 抛出的所有异常都继承 Fengz\KuaishouMiniapp\Exceptions\KuaishouMiniappException,按子类捕获可做精细控制:

try {
    KuaishouMiniapp::auth()->session($jsCode);
} catch (\Fengz\KuaishouMiniapp\Exceptions\KuaishouMiniappAuthorizationException $e) {
    // app_id / app_secret 错误或缺失 —— 检查配置
} catch (\Fengz\KuaishouMiniapp\Exceptions\KuaishouMiniappRequestException $e) {
    // 网络 / 传输层失败
} catch (\Fengz\KuaishouMiniapp\Exceptions\KuaishouMiniappApiException $e) {
    // 平台返回了非成功的 result
    // $e->errorCode()、$e->description()、$e->endpoint()、$e->rawResponse()
}

token 失效类错误(result == 100200102,"access_token 授权错误")会在自动刷新 token 后重试一次。

未覆盖的能力

以下能力不在本 SDK 范围内,以及原因:

epay(担保支付) —— 有自己的一套请求签名体系(排序参数 + secret,与 webhook 全文 MD5 不同),外加预支付/退款/查询/回调等接口。契约较复杂,值得单独立项;待各接口逐一核实后在后续版本加入。
垂类行业 API(电商/直播等)—— 行业专用,超出通用小程序 SDK 的范围。

测试

composer test       # Pest
composer analyse    # PHPStan(最高级别)
composer format     # Laravel Pint

许可证

MIT —— 详见 LICENSE。

fengz / kuaishou-miniapp-sdk

Maintainers

Package info

Statistics

Security