wechatpay guzzle middleware下載 - wechatpay guzzle middleware原始碼下載

wechatpay-guzzle-middleware

概覽

微信支付API v3的Guzzle HttpClient中介軟體Middleware，實現了請求簽章的產生與應答簽章的驗證。

如果你是使用Guzzle的商家開發者，可以在建構GuzzleHttpClient時將WechatPayGuzzleMiddleware傳入，得到的GuzzleHttpClient實例在執行請求時將自動攜帶身份認證訊息，並檢查應答的微信支付簽名。

專案狀態

目前版本為0.2.0測試版本。請商戶的專業技術人員在使用時注意系統和軟體的正確性和相容性，以及帶來的風險。

本專案處於維護狀態，我們推薦所有的開發者優先使用微信支付新的PHP 開發庫wechatpay-php。

環境要求

我們開發和測試使用的環境如下：

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

備註：不支持guzzle7 的具體原因可以見#54 的討論。依賴guzzle7 的開發者請使用wechatpay-php。

安裝

可以使用PHP套件管理工具composer引入SDK到專案：

Composer

方式一：在專案目錄中，透過composer命令列新增：

composer require wechatpay/wechatpay-guzzle-middleware

方式二：在專案的composer.json中加入以下設定：

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

新增配置後，執行安裝

composer install

開始

首先，透過WechatPayMiddlewareBuilder建構一個WechatPayMiddleware ，然後將其加入GuzzleHttpClient的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設定微信支付平台證書，而平台證書又只能透過呼叫取得平台證書介面下載。為了解開"死循環"，你可以在第一次下載平台憑證時，按照下述方法暫時"跳過」應答簽署的驗證。

 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 ();