Download the PHP package yoolo-mine/wecom-crypto without Composer

wecom-crypto

企业微信回调消息加解密库，适用于 Laravel。基于企业微信官方加解密方案 PHP 示例封装为 Composer 包。

环境要求

• PHP >= 7.4
• 扩展：openssl、dom、libxml
• Laravel 8.x / 9.x（或兼容的 illuminate/support、illuminate/config）

安装

安装后 Laravel 会自动发现并注册服务提供者，无需在 config/app.php 中手动添加。

配置

方式一：使用环境变量（推荐）

在项目 .env 中配置：

无需发布配置文件，包会通过默认配置读取上述环境变量。

方式二：发布配置文件

如需在应用内直接修改配置，可发布配置文件到 config/wecom_crypto.php：

发布后可在 config/wecom_crypto.php 中修改 encodingAesKey、token、corpId。

Laravel 集成说明

自动发现

包在 composer.json 中声明了 extra.laravel.providers，Laravel 5.5+ 会在执行 composer install/update 时自动发现并注册 WecomCryptoServiceProvider，无需在 config/app.php 的 providers 数组中手动添加。

配置来源与优先级

1. 若执行过 php artisan vendor:publish --tag=wecom-crypto-config，应用会使用 config/wecom_crypto.php 中的值（该文件通常通过 env() 读取 .env）。
2. 若未发布配置，包会使用包内默认配置（mergeConfigFrom），即直接读取 config('wecom_crypto.xxx')，而该值来自包自带的 config/wecom_crypto.php，其中已写 env('WECHAT_WORK_*', '')，因此只要在 .env 中配置即可生效。

多应用 / 多套回调配置

若需要对接多个企业微信应用或不同 ReceiveId（如自建应用与第三方应用），不要使用单例 app('wxcrypt')，而是在业务处按需实例化：

也可在配置文件中为不同应用定义多组 key，再按应用选择后传入 WXBizMsgCrypt。

手动注册服务提供者（可选）

若自动发现未生效（例如 Laravel 版本较旧或自定义了发现逻辑），可在 config/app.php 的 providers 数组中手动添加：

注意事项

• 企业微信回调会带 URL 参数 msg_signature、timestamp、nonce，GET 校验时还有 echostr；POST 消息体为加密的 XML，需将原始请求体传入 DecryptMsg（如 $request->getContent()），不要用已解析的 $request->all()。
• 生产环境请务必在 .env 中配置正确的 WECHAT_WORK_AES_KEY（43 位）、WECHAT_WORK_TOKEN、WECHAT_WORK_CORP_ID，并避免将上述信息提交到版本库。

使用

在 Laravel 中通过容器使用

包注册了单例 wxcrypt，可直接注入或从容器解析：

验证回调 URL（VerifyURL）

企业微信在配置回调 URL 时会发起 GET 校验，用本方法验证并返回需回显的明文：

解密回调消息（DecryptMsg）

收到企业微信 POST 的加密消息时，先解密再处理：

加密回复消息（EncryptMsg）

需要对企业微信回复加密消息时：

不使用 Laravel 容器时

也可直接实例化，适用于非 Laravel 或需要多套配置的场景：

示例：路由与控制器

以下为在企业微信后台配置的「接收消息服务器」对应的路由与控制器示例，便于直接接入 GET 校验与 POST 消息。

路由

在 routes/web.php 或 routes/api.php 中定义（企业微信要求回调 URL 可公网访问，若用 web.php 需注意 CSRF 排除）：

若使用 routes/web.php 且启用了 CSRF，需在 app/Http/Middleware/VerifyCsrfToken.php 的 $except 中排除该 URI，例如：

控制器示例

企业微信后台配置

1. 进入企业微信管理后台 → 应用管理 → 自建应用（或对应应用）→ 接收消息。
2. 设置「接收消息服务器」URL 为：https://你的域名/wecom/callback（与上面路由一致）。
3. 填写 Token、EncodingAESKey，并保存后使用「验证」按钮；验证通过即会请求上述 GET 接口并校验通过。

错误码

与企业微信官方文档一致，可使用 YooloMine\WecomCrypto\CallBack\ErrorCode 常量判断：

协议与参考

• 加解密协议与返回码以企业微信官方文档为准。
• 本包采用 MIT 协议。