PHPackages                             wechatpay/wechatpay-guzzle-middleware - 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. [HTTP & Networking](/categories/http)
4. /
5. wechatpay/wechatpay-guzzle-middleware

ActiveLibrary[HTTP & Networking](/categories/http)

wechatpay/wechatpay-guzzle-middleware
=====================================

WechatPay API V3 Guzzle Middleware

0.2.2(5y ago)208182.8k↓16.2%45[1 PRs](https://github.com/wechatpay-apiv3/wechatpay-guzzle-middleware/pulls)14Apache-2.0PHPPHP >=5.5

Since Sep 30Pushed 4y ago5 watchersCompare

[ Source](https://github.com/wechatpay-apiv3/wechatpay-guzzle-middleware)[ Packagist](https://packagist.org/packages/wechatpay/wechatpay-guzzle-middleware)[ Docs](https://wechatpay-api.gitbook.io/wechatpay-api-v3/)[ RSS](/packages/wechatpay-wechatpay-guzzle-middleware/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (4)Dependencies (1)Versions (9)Used By (14)

wechatpay-guzzle-middleware
===========================

[](#wechatpay-guzzle-middleware)

概览
--

[](#概览)

[微信支付API v3](https://wechatpay-api.gitbook.io/wechatpay-api-v3/)的[Guzzle HttpClient](http://docs.guzzlephp.org/)中间件Middleware，实现了请求签名的生成和应答签名的验证。

如果你是使用Guzzle的商户开发者，可以在构造`GuzzleHttp\Client`时将`WechatPayGuzzleMiddleware`传入，得到的`GuzzleHttp\Client`实例在执行请求时将自动携带身份认证信息，并检查应答的微信支付签名。

项目状态
----

[](#项目状态)

当前版本为`0.2.0`测试版本。请商户的专业技术人员在使用时注意系统和软件的正确性和兼容性，以及带来的风险。

本项目处于**维护**状态，我们推荐所有的开发者优先使用微信支付新的 PHP 开发库 [wechatpay-php](https://github.com/wechatpay-apiv3/wechatpay-php)。

环境要求
----

[](#环境要求)

我们开发和测试使用的环境如下：

- PHP 5.5+ / PHP 7.0+
- guzzlehttp/guzzle ^6.3

备注：不支持 guzzle7 的具体原因可以见 [\#54](https://github.com/wechatpay-apiv3/wechatpay-guzzle-middleware/issues/54) 的[讨论](https://github.com/wechatpay-apiv3/wechatpay-guzzle-middleware/issues/54#issuecomment-879602192)。依赖 guzzle7 的开发者请使用 [wechatpay-php](https://github.com/wechatpay-apiv3/wechatpay-php)。

安装
--

[](#安装)

可以使用PHP包管理工具composer引入SDK到项目中：

#### Composer

[](#composer)

方式一：在项目目录中，通过composer命令行添加：

```
composer require wechatpay/wechatpay-guzzle-middleware
```

方式二：在项目的composer.json中加入以下配置：

```
    "require": {
        "wechatpay/wechatpay-guzzle-middleware": "^0.2.0"
    }
```

添加配置后，执行安装

```
composer install
```

开始
--

[](#开始)

首先，通过`WechatPayMiddlewareBuilder`构建一个`WechatPayMiddleware`，然后将其加入`GuzzleHttp\Client`的`HandlerStack`中。我们提供相应的方法，可以方便的传入商户私钥和微信支付平台证书等信息。

```
use GuzzleHttp\Exception\RequestException;
use WechatPay\GuzzleMiddleware\WechatPayMiddleware;
use WechatPay\GuzzleMiddleware\Util\PemUtil;

// 商户相关配置
$merchantId = '1000100'; // 商户号
$merchantSerialNumber = 'XXXXXXXXXX'; // 商户API证书序列号
$merchantPrivateKey = PemUtil::loadPrivateKey('/path/to/mch/private/key.pem'); // 商户私钥
// 微信支付平台配置
$wechatpayCertificate = PemUtil::loadCertificate('/path/to/wechatpay/cert.pem'); // 微信支付平台证书

// 构造一个WechatPayMiddleware
$wechatpayMiddleware = WechatPayMiddleware::builder()
    ->withMerchant($merchantId, $merchantSerialNumber, $merchantPrivateKey) // 传入商户相关配置
    ->withWechatPay([ $wechatpayCertificate ]) // 可传入多个微信支付平台证书，参数类型为array
    ->build();

// 将WechatPayMiddleware添加到Guzzle的HandlerStack中
$stack = GuzzleHttp\HandlerStack::create();
$stack->push($wechatpayMiddleware, 'wechatpay');

// 创建Guzzle HTTP Client时，将HandlerStack传入
$client = new GuzzleHttp\Client(['handler' => $stack]);

// 接下来，正常使用Guzzle发起API请求，WechatPayMiddleware会自动地处理签名和验签
try {
    $resp = $client->request('GET', 'https://api.mch.weixin.qq.com/v3/...', [ // 注意替换为实际URL
        'headers' => [ 'Accept' => 'application/json' ]
    ]);

    echo $resp->getStatusCode().' '.$resp->getReasonPhrase()."\n";
    echo $resp->getBody()."\n";

    $resp = $client->request('POST', 'https://api.mch.weixin.qq.com/v3/...', [
        'json' => [ // JSON请求体
            'field1' => 'value1',
            'field2' => 'value2'
        ],
        'headers' => [ 'Accept' => 'application/json' ]
    ]);

    echo $resp->getStatusCode().' '.$resp->getReasonPhrase()."\n";
    echo $resp->getBody()."\n";
} catch (RequestException $e) {
    // 进行错误处理
    echo $e->getMessage()."\n";
    if ($e->hasResponse()) {
        echo $e->getResponse()->getStatusCode().' '.$e->getResponse()->getReasonPhrase()."\n";
        echo $e->getResponse()->getBody();
    }
    return;
}
```

### 上传媒体文件

[](#上传媒体文件)

```
// 参考上述指引说明，并引入 `MediaUtil` 正常初始化，无额外条件
use WechatPay\GuzzleMiddleware\Util\MediaUtil;
// 实例化一个媒体文件流，注意文件后缀名需符合接口要求
$media = new MediaUtil('/your/file/path/with.extension');

// 正常使用Guzzle发起API请求
try {
    $resp = $client->request('POST', 'https://api.mch.weixin.qq.com/v3/[merchant/media/video_upload|marketing/favor/media/image-upload]', [
        'body'    => $media->getStream(),
        'headers' => [
            'Accept'       => 'application/json',
            'content-type' => $media->getContentType(),
        ]
    ]);
    // POST 语法糖
    $resp = $client->post('merchant/media/upload', [
        'body'    => $media->getStream(),
        'headers' => [
            'Accept'       => 'application/json',
            'content-type' => $media->getContentType(),
        ]
    ]);
    echo $resp->getStatusCode().' '.$resp->getReasonPhrase()."\n";
    echo $resp->getBody()."\n";
} catch (Exception $e) {
    echo $e->getMessage()."\n";
    if ($e->hasResponse()) {
        echo $e->getResponse()->getStatusCode().' '.$e->getResponse()->getReasonPhrase()."\n";
        echo $e->getResponse()->getBody();
    }
    return;
}
```

### 敏感信息加/解密

[](#敏感信息加解密)

```
// 参考上上述说明，引入 `SensitiveInfoCrypto`
use WechatPay\GuzzleMiddleware\Util\SensitiveInfoCrypto;
// 上行加密API 多于 下行解密，默认为加密，实例后直接当方法用即可
$encryptor = new SensitiveInfoCrypto(PemUtil::loadCertificate('/path/to/wechatpay/cert.pem'));

// 正常使用Guzzle发起API请求
try {
    // POST 语法糖
    $resp = $client->post('/v3/applyment4sub/applyment/', [
        'json' => [
            'business_code' => 'APL_98761234',
            'contact_info'  => [
                'contact_name'      => $encryptor('value of `contact_name`'),
                'contact_id_number' => $encryptor('value of `contact_id_number'),
                'mobile_phone'      => $encryptor('value of `mobile_phone`'),
                'contact_email'     => $encryptor('value of `contact_email`'),
            ],
            //...
        ],
        'headers' => [
            // 命令行获取证书序列号
            // openssl x509 -in /path/to/wechatpay/cert.pem -noout -serial | awk -F= '{print $2}'
            // 或者使用工具类获取证书序列号 `PemUtil::parseCertificateSerialNo($certificate)`
            'Wechatpay-Serial' => 'must be the serial number via the downloaded pem file of `/v3/certificates`',
            'Accept'           => 'application/json',
        ],
    ]);
    echo $resp->getStatusCode().' '.$resp->getReasonPhrase()."\n";
    echo $resp->getBody()."\n";
} catch (Exception $e) {
    echo $e->getMessage()."\n";
    if ($e->hasResponse()) {
        echo $e->getResponse()->getStatusCode().' '.$e->getResponse()->getReasonPhrase()."\n";
        echo $e->getResponse()->getBody();
    }
    return;
}

// 单例加解密示例如下
$crypto = new SensitiveInfoCrypto($wechatpayCertificate, $merchantPrivateKey);
$encrypted = $crypto('Alice');
$decrypted = $crypto->setStage('decrypt')($encrypted);
```

定制
--

[](#定制)

当默认的本地签名和验签方式不适合你的系统时，你可以通过实现`Signer`或者`Verifier`来定制签名和验签。比如，你的系统把商户私钥集中存储，业务系统需通过远程调用进行签名，你可以这样做。

```
use WechatPay\GuzzleMiddleware\Auth\Signer;
use WechatPay\GuzzleMiddleware\Auth\SignatureResult;
use WechatPay\GuzzleMiddleware\Auth\WechatPay2Credentials;

class CustomSigner implements Signer
{
    public function sign($message)
    {
        // 调用签名RPC服务，然后返回包含签名和证书序列号的SignatureResult
        return new SignatureResult('xxxx', 'yyyyy');
    }
}

$credentials = new WechatPay2Credentials($merchantId, new CustomSigner);

$wechatpayMiddleware = WechatPayMiddleware::builder()
    ->withCredentials($credentials)
    ->withWechatPay([ $wechatpayCertificate ])
    ->build();
```

常见问题
----

[](#常见问题)

### 如何下载平台证书？

[](#如何下载平台证书)

使用`WechatPayMiddlewareBuilder`需要调用`withWechatpay`设置[微信支付平台证书](https://wechatpay-api.gitbook.io/wechatpay-api-v3/ren-zheng/zheng-shu#ping-tai-zheng-shu)，而平台证书又只能通过调用[获取平台证书接口](https://wechatpay-api.gitbook.io/wechatpay-api-v3/jie-kou-wen-dang/ping-tai-zheng-shu#huo-qu-ping-tai-zheng-shu-lie-biao)下载。为了解开"死循环"，你可以在第一次下载平台证书时，按照下述方法临时"跳过”应答签名的验证。

```
use WechatPay\GuzzleMiddleware\Validator;

class NoopValidator implements Validator
{
    public function validate(\Psr\Http\Message\ResponseInterface $response)
    {
        return true;
    }
}

$wechatpayMiddleware = WechatPayMiddleware::builder()
    ->withMerchant($merchantId, $merchantSerialNumber, $merchantPrivateKey)
    ->withValidator(new NoopValidator) // NOTE: 设置一个空的应答签名验证器，**不要**用在业务请求
    ->build();
```

**注意**：业务请求请使用标准的初始化流程，务必验证应答签名。

### 证书和回调解密需要的AesGcm解密在哪里？

[](#证书和回调解密需要的aesgcm解密在哪里)

请参考[AesUtil.php](src/Util/AesUtil.php)。

### 配合swoole使用时，上传文件接口报错

[](#配合swoole使用时上传文件接口报错)

建议升级至swoole 4.6+，swoole在 4.6.0 中增加了native-curl([swoole/swoole-src#3863](https://github.com/swoole/swoole-src/pull/3863))支持，我们测试能正常使用了。 更详细的信息，请参考[\#36](https://github.com/wechatpay-apiv3/wechatpay-guzzle-middleware/issues/36)。

联系我们
----

[](#联系我们)

如果你发现了**BUG**或者有任何疑问、建议，请通过issue进行反馈。

也欢迎访问我们的[开发者社区](https://developers.weixin.qq.com/community/pay)。

###  Health Score

39

—

LowBetter than 86% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity51

Moderate usage in the ecosystem

Community29

Small or concentrated contributor base

Maturity48

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 64% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~130 days

Total

5

Last Release

1901d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/22bcb06ec67676785c739e90097d894cb74e2fb7c8cdfc1e2ca688d42cbc24e1?d=identicon)[wechatpay](/maintainers/wechatpay)

---

Top Contributors

[![tpirc3](https://avatars.githubusercontent.com/u/29061068?v=4)](https://github.com/tpirc3 "tpirc3 (16 commits)")[![xy-peng](https://avatars.githubusercontent.com/u/1812516?v=4)](https://github.com/xy-peng "xy-peng (7 commits)")[![TheNorthMemory](https://avatars.githubusercontent.com/u/1631685?v=4)](https://github.com/TheNorthMemory "TheNorthMemory (1 commits)")[![Yurunsoft](https://avatars.githubusercontent.com/u/20104656?v=4)](https://github.com/Yurunsoft "Yurunsoft (1 commits)")

---

Tags

guzzle-middlewarephpwechatwechatpaywechatpay-apiv3wechatpay

### Embed Badge

![Health badge](/badges/wechatpay-wechatpay-guzzle-middleware/health.svg)

```
[![Health](https://phpackages.com/badges/wechatpay-wechatpay-guzzle-middleware/health.svg)](https://phpackages.com/packages/wechatpay-wechatpay-guzzle-middleware)
```

###  Alternatives

[friendsofsymfony/rest-bundle

This Bundle provides various tools to rapidly develop RESTful API's with Symfony

2.8k73.3M319](/packages/friendsofsymfony-rest-bundle)[php-http/discovery

Finds and installs PSR-7, PSR-17, PSR-18 and HTTPlug implementations

1.3k309.5M1.2k](/packages/php-http-discovery)[pusher/pusher-php-server

Library for interacting with the Pusher REST API

1.5k94.8M293](/packages/pusher-pusher-php-server)[react/http

Event-driven, streaming HTTP client and server implementation for ReactPHP

78026.4M414](/packages/react-http)[php-http/curl-client

PSR-18 and HTTPlug Async client with cURL

48347.0M384](/packages/php-http-curl-client)[smi2/phpclickhouse

PHP ClickHouse Client

84310.1M71](/packages/smi2-phpclickhouse)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)