Download the PHP package kode/miniapp without Composer
On this page you can find all versions of the php package kode/miniapp. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Package miniapp
Short Description 多平台小程序、公众号、企业号、微信开放平台统一接入 SDK(微信、支付宝、抖音、百度、QQ、企业微信、钉钉、飞书)
License Apache-2.0
Homepage https://github.com/kode-lab/miniapp
Informations about the package miniapp
Kode MiniApp
多平台小程序、公众号、企业号统一接入 SDK。
特性
- Union 统一调用入口(推荐):业务侧只需要
use Kode\MiniApp\Union\Union;一行代码,通过Union::wechat()->mini($code)一行完成跨平台登录、支付、回调,跨端账号自动合并(UnionID) - 多端登录约束(SessionManager):内置
SessionManager提供 4 种登录约束策略(多端可登录 / 单设备单账号 / 单账号单端 / 单账号全端),可应对优酷/腾讯视频/银行 App 等"禁止账号共享"场景 - 多平台统一接入:一套代码对接微信、支付宝、抖音、百度、QQ、企业微信、钉钉、飞书
- 微信生态互联:通过微信开放平台(Component)统一管理公众号、小程序、移动 App、PC 网站应用,账号体系(UnionID)互通
- PHP 8.4+ 现代化:使用 readonly、enum、match、构造函数属性提升、nullsafe、命名参数、
__call/__callStatic魔术分发等新特性 - 企业级能力:除 C 端小程序外,完整支持企业微信、钉钉、飞书的通讯录、审批、消息推送
- 服务端消息处理:统一处理各平台的消息推送和事件回调
- 企业级支付:2.0 起支付能力完全由
kode/pays承载(composer 硬依赖),下单 / 验签 / 退款 / 分账 / 转账 / 对账统一经 kode/pays,付款人身份(openid / buyer_id)由本包登录后自动注入 - 工具桥接:内置基础工具类,同时可桥接到
kode/tools企业级工具包 - 异常桥接:内置异常体系,同时可桥接到
kode/exception统一异常处理组件 - Kode 生态兼容:与 kode/pays、kode/tools、kode/exception、kode/cache、kode/event、kode/jwt 等包无缝协作
- 统一 API 响应与业务异常:
ApiResponse归一化各平台异构错误字段(errcode / err_no / errno / code / 支付宝 xxx_response.code / OAuth error),ApiException提供令牌失效、频率限制、可重试分类,业务侧可据此自动清缓存 / 退避 - AccessToken 自动缓存:基于 PSR-16 的令牌缓存 + 单飞锁(single-flight)防击穿,带安全边界提前过期,避免每次调用重复换取触发平台配额
- HTTP 重试与日志脱敏:可配置指数退避重试(遵循 Retry-After)、自定义中间件注入,敏感字段(secret / access_token / sign 等)在日志中自动掩码
v1.14.0 核心增强
- 新增
ApiResponse/ApiException/TokenManager/RetryPolicy/LogSanitizer/ArrayCache等核心组件,统一响应解析、令牌缓存、请求重试与日志脱敏。 - 支付宝统一网关
AlipayGateway收敛散落的签名逻辑,并修正签名串剔除空值 / 顶层参数误入biz_content两处缺陷,私钥兼容 PKCS#1 与 PKCS#8。 - 9 个平台 Auth 模块接入统一响应与令牌缓存,最低 PHP 要求保持
>= 8.3。
Kode 生态关联
Kode MiniApp 是 Kode 生态的重要组成部分,与以下包可协同工作:
| 包名 | 类型 | 说明 |
|---|---|---|
kode/pays |
require(硬依赖) | 企业级多平台聚合支付 SDK,2.0 起为唯一支付路径(下单 / 验签 / 退款 / 分账 / 转账 / 对账),付款人身份由本包登录后注入 |
kode/tools |
suggest | PHP 通用工具包(加解密、二维码、消息体等),安装后自动优先使用 |
kode/exception |
suggest | 统一异常处理组件,安装后扩展异常码体系 |
kode/cache |
suggest | 高性能缓存组件,支持 Redis/Memcached 等,SessionManager 默认基于 PSR-16 |
kode/event |
suggest | 轻量级事件编排库 |
kode/jwt |
可选 | JWT 签发/验证,建议与 SessionManager 配合使用(见下文) |
支持平台
| 平台 | 标识 | 类型 | 能力 | 详细文档 |
|---|---|---|---|---|
| 微信 | wechat |
C端 | 登录、JS-SDK、用户、素材、菜单、客服、消息、订阅消息、小程序码、数据分析、支付、订单物流同步、内容安全、URL Scheme/Link、插件管理、直播、附近小程序、门店、卡券、摇一摇、发票、连Wi-Fi、微信小店、红包、广告、即时配送、搜一搜、动态消息、设备功能、云开发、服务端、回调通知 | 查看 |
| 微信开放平台 | wechat_open |
C端 | 第三方平台代公众号 / 小程序、Component AccessToken、PreAuthCode、授权流程、消息加解密、移动 App / PC 网站应用登录与支付 | 查看 |
| 支付宝 | alipay |
C端 | 登录、支付、转账、账单、营销、会员、回调通知 | 查看 |
| 抖音 | douyin |
C端 | 登录、支付、视频、评论 | 查看 |
| 百度 | baidu |
C端 | 登录、支付、模板消息 | 查看 |
qq |
C端 | 登录、支付 | 查看 | |
| 微信企业号 | wechat_work |
B端 | 认证、通讯录、部门管理、客户联系、外部联系人、标签、消息、审批、素材管理、应用管理、OA打卡汇报、会议室、公费电话、日程、收集表、微盘、上下游、会话存档、服务端、回调通知 | 查看 |
| 钉钉 | dingtalk |
B端 | 认证、通讯录、消息、审批、群机器人、考勤、智能人事、日志、项目、智能工作流 | 查看 |
| 飞书 | lark |
B端 | 认证、通讯录、消息、审批、审批定义、多维表格、文档、日历、任务、知识库、邮件 | 查看 |
能力支持矩阵
标注「✅ 支持 / — 不适用或暂未支持」。客户端敏感数据解密与手机号获取的算法细节见下文「统一敏感数据」与 docs/union.md。
| 平台 | 登录 | 用户资料 | 客户端解密(encryptedData) | 手机号(code 换) | 手机号(encryptedData) | 支付 | 回调通知 |
|---|---|---|---|---|---|---|---|
| 微信(小程序 / 公众号 / H5 / PC / App) | ✅ | ✅ | ✅ | ✅ 小程序 | ✅ | ✅ 全端(JSAPI/APP/MWEB/NATIVE) + 服务商 | ✅ 全场景 |
| 微信开放平台 | ✅ | ✅ | — | — | — | — | — |
| 支付宝(小程序 / 生活号 / App) | ✅ | ✅ | ✅ response+sign | — | — | ✅ mini/mp/app | ✅ |
| 抖音(小程序) | ✅ | ✅ | ✅ | ✅ RSA 密文 | ✅ | ✅ 小程序 | ✅ 小程序 |
| 百度(小程序) | ✅ | ✅ | ✅ | — | ✅ | ✅ 小程序 | ✅ 小程序 |
| QQ(小程序) | ✅ | ✅ | ✅ | — | ✅ | ✅ 小程序 | ✅ 小程序 |
| 企业微信 | ✅ | ✅ | ✅ | — | ✅ | —(经 kode/pays) | ✅ |
| 钉钉 | ✅ | ✅ | — | — | — | — | — |
| 飞书 | ✅ | ✅ | ✅ hex 变体 | — | ✅ | — | — |
说明:
- 客户端解密(encryptedData):微信 / 抖音 / QQ / 百度 / 飞书 / 企业微信 走统一
Union::decrypt()/decryptByUser()(AES-128-CBC + watermark);支付宝走Union::alipay()->decrypt()(response+sign / RSA2 验签),不并入统一入口。 - 手机号(code 换):微信小程序
Union::phoneByCode()(明文);抖音Union::phoneByCode()(RSA 密文,需app_private_key)。 - 手机号(encryptedData):微信 / 抖音 / QQ / 百度 / 飞书 / 企业微信 走
Union::phoneByDecrypt()/phoneByUser();支付宝走Union::phoneByResponse()。 - 支付 / 回调:B 端平台(钉钉 / 飞书)及微信开放平台(第三方平台)无消费者支付场景,标记为「—」属设计预期。
高级支付能力矩阵(2.0 · kode/pays 桥接)
2.0 起支付完全由
kode/pays承载。Union::xxx()->advancedPay()/paymentCapabilities()/capabilityProfile()暴露 10 项高级能力(分账 / 转账 / 对账 / 红包 / 订阅 / 余额 / 结算 / 个人收款 / Webhook / 退款)。能力声明严格镜像 kode/pays 真实网关实现(零漂移,由PaysBridgeCapabilityMatrixConsistencyTest守护)。完整矩阵、跨渠道真实网关签名链 e2e 验证状态与「大声失败」契约见 docs/CAPABILITY_MATRIX.md。
| 能力 | 微信 V2 | 支付宝 | 抖音 | |
|---|---|---|---|---|
| 分账 / 转账 / 红包 / 订阅 / 对账 / 结算 / 个人收款 / 退款 | ✅ | ✅ | 分账 ✅、退款 ✅(其余 ❌) | 退款 ✅(其余 ❌) |
| 余额 | ❌ | ✅ | ❌ | ❌ |
| Webhook 事件 | ✅ | ✅ | ✅ | ✅ |
跨渠道签名对照:核心下单生命周期 + 高级能力(含个人收款)在 微信 V2(XML+MD5)× 支付宝(RSA2)双渠道均已 e2e 验证;微信 V3 入站解密 / 出站签名 / Webhook 验签双链均补齐。
安装
快速开始
架构设计
核心组件
- Kernel:统一门面,通过
$kernel->wechat()、$kernel->dingtalk()等快捷方法获取平台实例 - Provider:平台入口,管理配置和 HTTP 客户端,支持多应用实例
- App:应用实例,聚合该平台的所有能力模块
- Server:服务端消息处理器,统一处理各平台的消息推送和事件回调
- Message:消息构造器,构造被动回复消息
- Notify:支付回调通知处理器,自动验签并触发业务逻辑
- Union(推荐):统一入口门面,通过
Channel枚举 + 适配器屏蔽各平台差异 - PayBridge:支付桥接器,自动检测并桥接到
kode/pays企业级支付 SDK - ToolsBridge:工具桥接器,自动检测并优先使用
kode/tools工具类 - ExceptionBridge:异常桥接器,自动检测并扩展
kode/exception异常码体系
各平台详细文档
每个平台都有独立的详细使用文档,包含配置说明和各功能模块的完整使用示例:
| 平台 | 文档路径 | 说明 |
|---|---|---|
| Union 统一入口 | docs/union.md | 跨平台一键登录 / 支付 / 回调,跨端账号自动合并(推荐阅读) |
| 微信 | docs/wechat.md | 公众号/小程序,30+ 功能模块 |
| 微信开放平台 | docs/wechat-open.md | 第三方平台(代公众号 / 小程序),App / PC 互联 |
| 微信企业号 | docs/wechat-work.md | 企业微信,通讯录/审批/客户联系/会话存档 |
| 支付宝 | docs/alipay.md | 小程序/生活号,支付/转账/营销 |
| 抖音 | docs/douyin.md | 小程序,视频管理/支付 |
| 百度 | docs/baidu.md | 小程序,登录/支付/模板消息 |
| docs/qq.md | 小程序,登录/支付 | |
| 钉钉 | docs/dingtalk.md | 企业办公,通讯录/审批/考勤/智能人事 |
| 飞书 | docs/lark.md | 企业办公,通讯录/审批/多维表格/文档/日历 |
各平台详细配置
微信
微信开放平台
支付宝
抖音
百度
微信企业号
钉钉
飞书
平台能力使用
快速开始(5 行代码接入全平台)
业务侧只需要
use Kode\MiniApp\Union\Union;一行代码,通过静态方法即可访问所有平台。
统一敏感数据(手机号 / 用户资料 / 加密数据)
小程序客户端回传的 encryptedData、手机号 code,经本 SDK 统一解密 / 校验后返回强类型值对象或归一化数组,业务侧无需关心各端算法差异(AES-128-CBC + watermark / 支付宝 RSA2 / 抖音 RSA 密文)。登录成功即自动托管 session_key,后续解密可一键取用,无需手动传递密钥。
三族统一入口
| 能力 | 数组入口 | 值对象入口 | 覆盖渠道 |
|---|---|---|---|
| 通用加密数据 data | Union::decrypt() / decryptByUser() |
— | 微信/抖音/QQ/百度/飞书/企业微信(支付宝走 Union::alipay()->decrypt()) |
| 手机号 phone | Union::phoneByCode() / phoneByDecrypt() / phoneByUser() / phoneByResponse() |
Union::phoneObjectBy* |
code:微信/抖音;encryptedData:微信/抖音/QQ/百度/飞书/企业微信;response:支付宝 |
| 用户资料 userInfo | Union::userInfoByDecrypt() / userInfoByUser() |
Union::userInfoObjectBy* |
微信/抖音/QQ/百度/飞书/企业微信 |
典型用法
完整算法说明、失败语义(统一抛
ApiException)、各端字段差异对照表见 docs/union.md。 敏感密钥(session_key/aes_key)已在日志脱敏键中,严禁下发前端或写入日志。
多端登录约束(SessionManager)
业务场景:1 个用户可能从小程序、APP、PC、公众号等多个端口登录。 某些业务(优酷/腾讯视频/银行 App)需要约束登录端口,防止账号共享或设备被顶替。
SDK 内置 SessionManager 提供 4 种登录约束策略:
| 策略 | 含义 | 适用场景 |
|---|---|---|
Multi |
多端可同时登录(默认) | 通用应用 |
SingleEnd |
单设备单账号(同设备只能登录 1 个账号) | 共享设备、家庭账户 |
SingleUser |
单账号单端(同账号同端口重复登录踢旧) | 跨端允许,限同端重复 |
SingleAll |
单账号全端(同账号只能登录 1 次) | 优酷、腾讯视频、银行 App |
与 kode/jwt 的关系(设计边界)
| 关注点 | 归属 |
|---|---|
| Token 签发 / 验证 / 刷新 | kode/jwt(stateless) |
| Token 黑名单 / 撤销 | kode/jwt(通过 jti) |
| 登录约束 / 多端踢人 | kode/miniapp SessionManager(stateful) |
| 业务侧权限 / 角色 | 业务侧 |
业务侧典型组合用法:
四种策略对比
显式创建 Session
Session 存储扩展
SessionManager 底层使用 PSR-16 Cache 接口,可注入任何实现:
核心设计:Union 静态门面
| 调用 | 等价写法 | 说明 |
|---|---|---|
Union::wechat() |
$kernel->union()->wechat() |
微信生态聚合(公众号/小程序/H5/PC/App/开放平台) |
Union::wechatOpen() |
$kernel->union()->wechatOpen() |
微信开放平台(第三方平台) |
Union::alipay() |
$kernel->union()->alipay() |
支付宝聚合(小程序/生活号/App) |
Union::douyin() |
$kernel->union()->douyin() |
抖音聚合(小程序/头条号) |
Union::baidu() |
$kernel->union()->baidu() |
百度智能小程序 |
Union::qq() |
$kernel->union()->qq() |
QQ 聚合 |
Union::wechatWork() / Union::work() |
$kernel->union()->wechatWork() |
企业微信聚合 |
Union::dingtalk() |
$kernel->union()->dingtalk() |
钉钉聚合 |
Union::lark() |
$kernel->union()->lark() |
飞书聚合 |
平台聚合类(Platform Union)
每个平台聚合类(AlipayUnion 等)提供以下统一方法:
场景登录(最常用)
| 方法 | 适用场景 |
|---|---|
->mini($code) |
小程序 / 默认登录 |
->mp($code) |
公众号 |
->h5($code) |
H5 |
->pc($code) |
PC 网站应用 |
->app($code) |
移动 App |
->open($payload) |
开放平台(authorization_code) |
->suite($code) |
企业微信套件 |
->login($payload, $scene) |
通用登录(自定义 payload + 场景) |
四大能力
底层 Provider 访问
如需细粒度控制,可访问平台原始 Provider / App:
跨端账号合并(UnionID)
配置好微信开放平台(同一开放平台下绑定所有应用)后,跨端账号自动合并:
自定义适配器(业务扩展)
底层 vs 统一入口
| 维度 | 底层 Provider / App | Union 统一入口 |
|---|---|---|
| 适用对象 | 框架开发者、扩展定制 | 业务开发者(99% 场景) |
| 能力粒度 | 30+ 模块细粒度 | 场景登录 + 4 大能力 + 透传 Provider |
| 学习成本 | 高(需了解每个模块) | 极低(几行代码搞定) |
| 跨平台切换 | 需重写业务 | 无缝切换 |
| UnionID 处理 | 手动 | 自动 |
设计哲学:底层 Provider/App 是 SDK 的"零件库",Union 是面向业务场景的"成品工具"。 业务侧 99% 的需求都可以用 Union 解决,仅在需要极细粒度控制时才用底层 Provider。
详细文档
每个平台都有独立的详细使用文档:
| 平台 | 文档路径 | 说明 |
|---|---|---|
| Union 统一入口 | docs/union.md | 跨平台一键登录 / 支付 / 回调,跨端账号自动合并(推荐阅读) |
| 微信 | docs/wechat.md | 公众号/小程序,30+ 功能模块 |
微信服务端消息处理
微信/支付宝支付回调通知
统一支付回调(Union 入口)
除各 Provider 自带 notify()(含签名验签)外,Union 还提供跨端统一的回调
归一化入口,适合「一个回调控制器按渠道分发」的场景,与统一登录 / 支付 / 解密入口对称:
注意:
Union::notify()->decode()仅做字段归一化,不验签。微信 / 支付宝 / 抖音 / 百度 / 企业微信的回调签名验签请使用各 Provider 自带的notify()(上文 Provider 级用法); QQ 回调由Qq\Modules\Notify内部完成 XML+MD5 验签,建议直接用$kernel->qq()->app()->notify()。 业务侧务必在decode()之前完成签名校验,避免伪造回调。
微信企业号
钉钉
飞书
支付宝
抖音
百度
Kode 生态桥接使用
支付(kode/pays,2.0 起为唯一支付路径)
2.0 起支付能力完全由 kode/pays 承载,安装本包即需 composer require kode/pays(硬依赖):
桥接内部类 Kode\MiniApp\Union\Bridge\PaysBridge 提供诊断与自定义 resolver(available() /
adapter() / notifyAdapter() 等);未安装 kode/pays 时 Union::pay() / Union::notify()
会直接抛出清晰异常,引导先 composer require kode/pays。
工具桥接(kode/tools)
异常桥接(kode/exception)
HTTP 客户端
SDK 内置基于 Guzzle 的 HTTP 客户端,支持中间件、重试、日志:
缓存
SDK 推荐直接使用 SessionManager 进行会话/约束管理(见上文),底层基于 PSR-16 Cache 接口, 可注入任何实现(Redis / Memcached / 文件 等):
历史类说明:
Kode\MiniApp\Core\Cache和Kode\MiniApp\Core\AccessToken是早期为手动管理 AccessToken 缓存提供的工具类。SDK 内部已不再使用,业务侧推荐使用kode/cache+ SessionManager 的组合。如确有需要,可继续使用这两个类(保持向后兼容)。
工具类
异常处理
版本管理
版本号由 composer.json 统一管理:
代码质量
扩展新平台
扩展 Union 平台聚合(业务侧主入口)
src/Union/Platforms/下创建新的XxxUnion.php继承PlatformUnionsrc/Union/Union.php的PLATFORM_MAP中添加映射tests/Union/PlatformUnionTest.php编写测试
业务侧立即可用:
扩展 Provider(底层细粒度接口)
src/Contracts/Platform.php添加枚举值src/Providers/{Platform}/实现 Provider、App、Config、Modulessrc/Kernel.php注册 Providertests/Providers/{Platform}/编写测试
扩展 Union 适配器(底层协议适配)
src/Union/Channel.php添加渠道枚举src/Union/Channels/{Platform}/实现 LoginAdapter / UserAdapter / PayAdapter / NotifyAdaptersrc/Union/Union.php的build*Adapter()match 中添加渠道路由tests/Union/编写测试
许可证
Apache License 2.0
All versions of miniapp with dependencies
ext-mbstring Version *
ext-json Version *
ext-openssl Version *
guzzlehttp/guzzle Version ^7.8
kode/pays Version ^3
psr/simple-cache Version ^3.0
psr/log Version ^3.0
symfony/cache Version ^6.4|^7.0
monolog/monolog Version ^3.5