PHPackages                             sakuara-bj/wxbizmsgcrypt - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. sakuara-bj/wxbizmsgcrypt

ActiveLibrary

sakuara-bj/wxbizmsgcrypt
========================

Enterprise WeChat Callback

v1.0.1(2mo ago)1728↓100%MITPHPPHP >=7.4

Since Jan 29Pushed 2mo ago1 watchersCompare

[ Source](https://github.com/yoolo-mine/wxbizmsgcrypt)[ Packagist](https://packagist.org/packages/sakuara-bj/wxbizmsgcrypt)[ RSS](/packages/sakuara-bj-wxbizmsgcrypt/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (3)Versions (4)Used By (0)

wecom-crypto
============

[](#wecom-crypto)

企业微信回调消息加解密库，适用于 Laravel。基于[企业微信官方加解密方案](https://developer.work.weixin.qq.com/document/path/90307) PHP 示例封装为 Composer 包。

环境要求
----

[](#环境要求)

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

安装
--

[](#安装)

```
composer require yoolo-mine/wecom-crypto
```

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

配置
--

[](#配置)

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

[](#方式一使用环境变量推荐)

在项目 `.env` 中配置：

```
WECHAT_WORK_AES_KEY=你的EncodingAESKey（43位）
WECHAT_WORK_TOKEN=你的Token
WECHAT_WORK_CORP_ID=你的CorpID或应用场景对应的ReceiveId
```

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

### 方式二：发布配置文件

[](#方式二发布配置文件)

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

```
php artisan vendor:publish --tag=wecom-crypto-config
```

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

Laravel 集成说明
------------

[](#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')`，而是在业务处按需实例化：

```
use YooloMine\WecomCrypto\WXBizMsgCrypt;

$wxcpt = new WXBizMsgCrypt(
    config('wecom_crypto.token'),
    config('wecom_crypto.encodingAesKey'),
    'different_receive_id_for_this_app'
);
```

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

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

[](#手动注册服务提供者可选)

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

```
'providers' => [
    // ...
    YooloMine\WecomCrypto\Providers\WecomCryptoServiceProvider::class,
],
```

### 注意事项

[](#注意事项)

- 企业微信回调会带 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 中通过容器使用

[](#在-laravel-中通过容器使用)

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

```
use YooloMine\WecomCrypto\CallBack\ErrorCode;

// 解析单例（使用 .env 或 config/wecom_crypto.php 中的配置）
$wxcpt = app('wxcrypt');
```

### 验证回调 URL（VerifyURL）

[](#验证回调-urlverifyurl)

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

```
$result = $wxcpt->VerifyURL(
    $request->query('msg_signature'),
    $request->query('timestamp'),
    $request->query('nonce'),
    $request->query('echostr')
);

if ($result === ErrorCode::IllegalAesKey) {
    // EncodingAESKey 长度不是 43
}
if ($result === ErrorCode::ValidateSignatureError) {
    // 签名校验失败
}
if (is_int($result) && $result < 0) {
    // 其他错误码，见下方「错误码」
}

// 成功：$result 为解密后的明文字符串，直接返回给企业微信
return response($result);
```

### 解密回调消息（DecryptMsg）

[](#解密回调消息decryptmsg)

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

```
$sMsg = '';
$errCode = $wxcpt->DecryptMsg(
    $request->query('msg_signature'),
    $request->query('timestamp'),
    $request->query('nonce'),
    $request->getContent(),
    $sMsg
);

if ($errCode !== ErrorCode::OK) {
    // 根据错误码处理，见下方「错误码」
    return response()->json(['error' => $errCode], 400);
}

// $sMsg 为解密后的 XML 字符串
$xml = simplexml_load_string($sMsg);
// 后续业务逻辑...
```

### 加密回复消息（EncryptMsg）

[](#加密回复消息encryptmsg)

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

```
$sEncryptMsg = '';
$errCode = $wxcpt->EncryptMsg(
    $replyXmlString,      // 要回复的 XML 明文
    $request->query('timestamp'),
    $request->query('nonce'),
    $sEncryptMsg
);

if ($errCode !== ErrorCode::OK) {
    return response()->json(['error' => $errCode], 500);
}

// $sEncryptMsg 为加密后的完整 XML，可直接返回
return response($sEncryptMsg)->header('Content-Type', 'text/xml');
```

### 不使用 Laravel 容器时

[](#不使用-laravel-容器时)

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

```
use YooloMine\WecomCrypto\WXBizMsgCrypt;

$wxcpt = new WXBizMsgCrypt(
    'your_token',
    'your_encoding_aes_key_43_chars',
    'your_corp_id_or_receive_id'
);
// 之后调用 VerifyURL、DecryptMsg、EncryptMsg 同上
```

示例：路由与控制器
---------

[](#示例路由与控制器)

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

### 路由

[](#路由)

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

```
use App\Http\Controllers\WecomCallbackController;

// 企业微信应用回调：GET 用于校验 URL，POST 用于接收消息
Route::match(['get', 'post'], 'wecom/callback', [WecomCallbackController::class, 'handle'])
    ->name('wecom.callback');
```

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

```
protected $except = [
    'wecom/callback',
];
```

### 控制器示例

[](#控制器示例)

```