README

面向微信公众号/小程序/支付/服务器的纯 PHP SDK，目标是调用简单、参数最少、功能整合、封装完整。

安装

composer require p18/cp_weixin

快速开始（公众号 OAuth）

<?php

use CpWeixin\Weixin;

$user = Weixin::officialAccount([
    'appid' => 'wx_xxx',
    'secret' => 'secret_xxx',
])->getUserInfoByCode($_GET['code'] ?? '');

微信扫码授权登录（PC网站）

<?php

use CpWeixin\Weixin;

$oa = Weixin::officialAccount([
    'appid' => 'wx_xxx',        // 微信开放平台网站应用的 AppID
    'secret' => 'secret_xxx',   // 微信开放平台网站应用的 AppSecret
]);

// 生成扫码授权登录链接
$qrconnectUrl = $oa->qrconnectUrl('https://example.com/callback', 'state_123');

// 在回调页面处理
if (isset($_GET['code'])) {
    $userInfo = $oa->getUserInfoByCode($_GET['code']);
    // 处理登录逻辑...
}

公众号服务器（一键处理）

<?php

use CpWeixin\Weixin;
use CpWeixin\OfficialAccount\Reply;

$oa = Weixin::officialAccount([
    'appid' => 'wx_xxx',
    'secret' => 'secret_xxx',
    'token' => 'token_xxx',
    'encodingaeskey' => 'encodingaeskey_xxx',  // 可选，启用消息加密
]);

// 配置消息路由
$router = $oa->router()
    ->onMessage('text', function (array $msg) {
        return Reply::text('收到：' . ($msg['Content'] ?? ''));
    })
    ->onEvent('subscribe', function () {
        return Reply::text('欢迎关注');
    })
    ->fallback(function () {
        return 'success';
    });

// 一键处理（自动验证签名、处理首次接入、处理消息、自动加密/解密）
echo $oa->server()->serve($router);

公众号 API 示例（菜单）

<?php

use CpWeixin\Weixin;

$resp = Weixin::officialAccount([
    'appid' => 'wx_xxx',
    'secret' => 'secret_xxx',
])->menuCreate([
    [
        'type' => 'view',
        'name' => '官网',
        'url' => 'https://example.com',
    ],
]);

小程序示例（登录）

<?php

use CpWeixin\Weixin;

$session = Weixin::miniProgram([
    'appid' => 'wx_xxx',
    'secret' => 'secret_xxx',
])->codeToSession($_GET['code'] ?? '');

// $session 可能包含 unionid（如果小程序绑定了开放平台）

获取 UnionID（无需网页授权）

<?php

use CpWeixin\Weixin;

// 方式一：公众号已关注用户（无需授权）
$oa = Weixin::officialAccount([
    'appid' => 'wx_xxx',
    'secret' => 'secret_xxx',
]);
$userInfo = $oa->getUserInfo('openid_xxx'); // 包含 unionid

// 方式二：小程序支付后获取（无需授权）
$mp = Weixin::miniProgram([
    'appid' => 'wx_xxx',
    'secret' => 'secret_xxx',
]);
$result = $mp->getPaidUnionId('openid_xxx', 'transaction_id_xxx');

// 方式三：小程序登录（可能包含 unionid，无需授权）
$session = $mp->codeToSession('js_code_xxx'); // 可能包含 unionid

支付 JSAPI 示例

<?php

use CpWeixin\Weixin;

$resp = Weixin::pay([
    'appid' => 'wx_xxx',
    'mch_id' => '1900000109',
    'serial_no' => '77759EF9F2D4C5C6',
    'private_key_path' => '/path/to/apiclient_key.pem',
    'api_v3_key' => 'api_v3_key_xxx',
])->jsapi([
    'description' => '商品描述',
    'out_trade_no' => 'ORDER_123',
    'notify_url' => 'https://example.com/notify',
    'amount' => ['total' => 1, 'currency' => 'CNY'],  // amount 为对象，包含 total（分）和 currency
    'payer' => ['openid' => 'OPENID'],  // payer 为对象，包含 openid
]);

支付回调处理（一键处理）

<?php

use CpWeixin\Weixin;

$pay = Weixin::pay([
    'appid' => 'wx_xxx',
    'mch_id' => '1900000109',
    'serial_no' => '77759EF9F2D4C5C6',
    'private_key_path' => '/path/to/apiclient_key.pem',
    'api_v3_key' => 'api_v3_key_xxx',
    'pay_cert_cache' => '/path/to/cert_cache',
]);

// 一键处理支付回调（自动验证签名、解密、处理）
echo $pay->notify()->serve(function (array $data) {
    $eventType = $data['event_type'] ?? '';
    if ($eventType === 'TRANSACTION.SUCCESS') {
        $resource = $data['resource'] ?? [];
        $outTradeNo = $resource['out_trade_no'] ?? '';
        // 处理业务逻辑...
    }
});

小程序物流回调（一键处理）

<?php

use CpWeixin\Weixin;

$mp = Weixin::miniProgram([
    'appid' => 'wx_xxx',
    'secret' => 'secret_xxx',
    'logistics_token' => 'logistics_token_xxx',
]);

// 一键处理物流回调（自动验证签名、解析、处理）
echo $mp->logisticsServer()->serve(function (array $data) {
    // 处理业务逻辑...
    return 'success';
});

模块方法列表

公众号 OAuth 模块

oauthUrl 生成 OAuth 授权链接（公众号网页授权，微信内打开）
qrconnectUrl 生成扫码授权登录链接（PC网站扫码登录）
oauthState 生成 state
verifyState 校验 state
oauthAccessToken code 换取 OAuth access_token
oauthUserInfo 使用 OAuth access_token 获取用户信息
getUserInfoByCode 一步获取 OAuth 用户信息
getUserInfo 无需授权获取用户信息（已关注用户，包含 unionid）

公众号服务器模块

server 获取服务器处理实例
router 创建消息路由器
Server::serve 一键处理服务器请求（自动验证签名、首次接入、消息处理、加密/解密）
Server::validate 校验签名
Server::echoStr 首次接入回显
Server::handle 处理消息并返回 XML（支持消息加密）
MessageRouter::onMessage 注册消息处理器
MessageRouter::onEvent 注册事件处理器
MessageRouter::fallback 注册兜底处理器
MessageRouter::dispatch 分发消息
Reply::text 构建文本回复
Reply::image 构建图片回复
Reply::voice 构建语音回复
Reply::video 构建视频回复
Reply::music 构建音乐回复
Reply::news 构建图文回复（单条/多条）
Reply::newsItem 构建图文项
MessageCrypt 消息加解密工具（自动处理，无需直接调用）

公众号 API 模块

getUserInfo 获取用户信息
getUserList 获取用户列表
batchGetUserInfo 批量获取用户信息
userRemark 设置用户备注名
blacklistGet 获取黑名单列表
blacklistAdd 批量加入黑名单
blacklistRemove 批量移出黑名单
menuCreate 创建自定义菜单
menuGet 获取菜单配置
menuDelete 删除菜单
qrcodeCreateTemporary 创建临时二维码
qrcodeCreatePermanent 创建永久二维码
qrcodeUrl 获取二维码图片链接
shortUrl 长链接转短链接
templateSend 发送模板消息
templateList 获取模板列表
templateDelete 删除模板
customerServiceSendText 发送客服文本消息
customerServiceSendImage 发送客服图片消息
customerServiceSendVoice 发送客服语音消息
customerServiceSendVideo 发送客服视频消息
customerServiceSendMusic 发送客服音乐消息
customerServiceSendNews 发送客服图文消息（单条）
customerServiceSendMpNews 发送客服图文消息（多条）
customerServiceSendCard 发送客服卡券消息
customerServiceSendMiniProgramPage 发送客服小程序卡片消息
tagGet 获取全部标签
tagCreate 创建标签
tagUpdate 更新标签
tagDelete 删除标签
tagUsers 获取标签下用户
tagBatch 批量打/取消标签
getJsApiTicket 获取 JSAPI ticket
jsApiSignature 生成 JS-SDK 签名
jsApiConfig 生成 JS-SDK 配置
mediaUpload 上传临时素材
mediaUploadImage 上传图文内图片
materialAdd 上传永久素材
materialAddNews 新增永久图文素材
materialUpdateNews 更新永久图文素材
materialDelete 删除永久素材
materialCount 获取素材总数
materialBatchGet 批量获取素材列表
materialGet 获取永久素材

小程序模块

logisticsServer 获取物流回调处理实例
codeToSession code 换取 session 信息（可能包含 unionid，无需授权）
getPhoneNumber 获取手机号
decryptUserData 解密用户数据
getPaidUnionId 通过支付获取 UnionID（无需授权）
getWxaCode 生成小程序码（数量限制）
getWxaCodeUnlimit 生成小程序码（无限制）
createWxaQrCode 生成二维码
generateUrlScheme 生成 URL Scheme
generateUrlLink 生成 URL Link
generateShortLink 生成短链
getAccountBasicInfo 获取账号基本信息
getCategory 获取可选类目
getCategoryList 获取已设置类目
getPage 获取页面列表
codeCommit 上传代码并生成体验版
codeGetQrCode 获取体验版二维码
codeSubmitAudit 提交审核
codeGetAuditStatus 查询审核状态
codeGetLatestAuditStatus 查询最新审核状态
codeRelease 发布版本
codeGetVersionInfo 查询版本信息
codeSpeedupAudit 加速审核
codeQueryQuota 查询审核配额
codeRollbackRelease 撤回已发布版本
codeBindTester 绑定体验者
codeUnbindTester 解除体验者
codeGetTesterList 获取体验者列表
getPrivacySetting 查询隐私配置
setPrivacySetting 设置隐私配置
subscribeSend 发送订阅消息
subscribeTemplateAdd 订阅模板：添加
subscribeTemplateDelete 订阅模板：删除
subscribeTemplateGetList 订阅模板：列表
subscribeTemplateGetPubTitles 订阅模板：公共标题
subscribeTemplateGetPubKeywords 订阅模板：关键词
customerServiceSendText 发送客服文本消息
customerServiceAdd 客服：新增账号
customerServiceUpdate 客服：更新账号
customerServiceDelete 客服：删除账号
customerServiceGetList 客服：账号列表
customerServiceGetOnlineList 客服：在线列表
customerServiceUploadHeadImg 客服：设置头像
msgSecCheck 文本内容安全检测
imgSecCheck 图片内容安全检测
mediaCheckAsync 异步媒体内容安全检测
setSearchStatus 设置搜索开关
getSearchStatus 获取搜索开关状态
getDailyVisitTrend 获取日访问趋势
getWeeklyVisitTrend 获取周访问趋势
getMonthlyVisitTrend 获取月访问趋势
getVisitTrend 获取访问趋势
getDailySummary 获取日累计概况
getVisitDistribution 获取访问分布
getVisitPage 获取访问页面
getUserPortrait 获取用户画像
liveCreateRoom 创建直播间
liveUpdateRoom 更新直播间
liveDeleteRoom 删除直播间
getLiveInfo 获取直播间列表
getLiveReplay 获取直播回放列表
liveGetPushUrl 获取直播间推流地址
liveGoodsAdd 直播商品：添加
liveGoodsAudit 直播商品：提交审核
liveGoodsResetAudit 直播商品：撤回审核
liveGoodsDelete 直播商品：删除
liveGoodsGetWarehouse 直播商品：列表
liveGoodsPush 直播商品：推送到直播间
liveGoodsSort 直播商品：排序
logisticsAddOrder 物流：创建运单
logisticsGetOrder 物流：查询运单
logisticsCancelOrder 物流：取消运单
logisticsGetAllOrders 物流：获取所有运单
logisticsGetAllDelivery 物流：获取快递公司列表
logisticsOpenMessage 物流：开通通知
logisticsUpdatePath 物流：更新运单轨迹
logisticsGetPath 物流：获取运单轨迹

小程序物流回调模块

logisticsServer 获取物流回调处理实例
LogisticsServer::serve 一键处理物流回调（自动验证签名、解析、处理）
LogisticsServer::validate 校验回调签名
LogisticsServer::parseJson 解析回调 JSON
LogisticsServer::handle 处理回调内容
LogisticsServer::success 返回成功响应

支付模块

支付下单

jsapi JSAPI 支付
h5 H5 支付
native Native 支付
app App 支付
combine 合单支付下单
serviceProvider 获取服务商模块实例

订单管理

queryByTransactionId 通过微信订单号查询
queryByOutTradeNo 通过商户订单号查询
close 关闭订单
confirm 确认收货（虚拟产品订单完成，解冻资金）
combineQuery 查询合单订单
combineClose 关闭合单订单

退款管理

refund 申请退款
refundQuery 查询退款（商户退款单号）
refundQueryByRefundId 查询退款（微信退款单号）

分账管理

profitSharing 请求分账
profitSharingQuery 查询分账结果
profitSharingReturn 请求分账回退
profitSharingReturnQuery 查询分账回退结果
profitSharingUnfreeze 解冻剩余资金
profitSharingQueryRatio 查询最大分账比例
profitSharingAddReceiver 添加分账接收方
profitSharingDeleteReceiver 删除分账接收方

转账管理

transferToBalance 转账到零钱
transferQueryBatch 查询转账批次单
transferQueryDetail 查询转账明细单
transferReceipt 查询转账明细电子回单

账单管理

tradeBill 申请交易账单
fundflowBill 申请资金账单
downloadBill 下载账单文件

证书与回调

certificates 获取平台证书
buildJsapiConfig 生成 JSAPI 配置
certificatesManager 证书管理器
notify 支付通知处理
Notify::serve 一键处理支付回调（自动获取请求头/体、校验签名、解密、处理）
Notify::verify 校验回调签名
Notify::decryptResource 解密回调资源数据
Notify::parse 解析支付回调数据
Notify::success 返回成功响应
Notify::fail 返回失败响应

服务商模块

服务商支付下单

jsapi 服务商 JSAPI 支付（代子商户下单）
h5 服务商 H5 支付（代子商户下单）
native 服务商 Native 支付（代子商户下单）
app 服务商 App 支付（代子商户下单）
combine 服务商合单支付下单

服务商订单管理

queryByTransactionId 服务商查询订单（微信支付订单号）
queryByOutTradeNo 服务商查询订单（商户订单号）
close 服务商关闭订单
confirm 服务商确认收货（虚拟产品订单完成，解冻资金）
combineQuery 服务商查询合单订单
combineClose 服务商关闭合单订单

服务商退款管理

refund 服务商申请退款
refundQuery 服务商查询退款（商户退款单号）
refundQueryByRefundId 服务商查询退款（微信退款单号）

子商户进件管理

applymentSubmit 提交子商户进件申请
applymentQuery 查询申请单状态（申请单 ID）
applymentQueryByBusinessCode 查询申请单状态（业务申请编号）
modifySettlement 修改结算账号
querySettlement 查询结算账号

子商户管理

querySubMerchant 查询子商户信息
querySubMerchantList 查询子商户列表（支持分页）
modifySubMerchant 修改子商户信息
modifySubMerchantStatus 修改子商户状态（启用/停用）
querySubMerchantRate 查询子商户费率配置
modifySubMerchantRate 修改子商户费率配置
querySubMerchantBalance 查询子商户资金账户余额
querySubMerchantFundflow 查询子商户资金流水
querySubMerchantOrders 批量查询子商户订单
querySubMerchantRefunds 批量查询子商户退款

服务商分账管理

profitSharing 服务商分账
profitSharingQuery 服务商查询分账结果
profitSharingReturn 服务商分账回退
profitSharingReturnQuery 服务商查询分账回退结果
profitSharingUnfreeze 服务商解冻剩余资金
profitSharingQueryRatio 服务商查询最大分账比例
profitSharingAddReceiver 服务商添加分账接收方
profitSharingDeleteReceiver 服务商删除分账接收方

服务商转账管理

transferToBalance 服务商转账到零钱
transferQueryBatch 服务商查询转账批次单
transferQueryDetail 服务商查询转账明细单
transferReceipt 服务商查询转账明细电子回单

服务商账单管理

tradeBill 服务商申请交易账单
fundflowBill 服务商申请资金账单
downloadBill 服务商下载账单文件

服务商 JSAPI 配置

buildJsapiConfig 生成服务商 JSAPI 调起支付配置
miniProgram 获取服务商小程序模块实例

服务商小程序模块

小程序授权管理

getPreAuthCode 获取预授权码（用于小程序授权）
authorizationUrl 生成小程序授权链接
getAuthorizationInfo 使用授权码获取授权信息
getAuthorizerInfo 获取授权方信息（小程序信息）
getAuthorizerAccessToken 获取授权方 access_token
getAuthorizerList 获取授权方列表

服务商小程序支付

jsapi 服务商代小程序支付下单（需要 sub_appid 和 sub_mchid）

服务商小程序登录

codeToSession 服务商小程序登录（通过 code 获取 session，需要 sub_appid）

配置项

appid 应用 AppID
secret 应用 AppSecret
token 公众号服务器配置 Token
encodingaeskey 消息加解密密钥（43位，可选，启用后自动处理加密/解密）
logistics_token 物流回调 Token（小程序）
mch_id 商户号
serial_no 商户证书序列号
private_key_path 商户私钥文件路径
api_v3_key APIv3 密钥
pay_cert_cache 支付证书缓存目录
component_appid 第三方平台 AppID（服务商小程序授权，可选）
component_appsecret 第三方平台 AppSecret（服务商小程序授权，可选）
component_verify_ticket 第三方平台验证票据（服务商小程序授权，可选）
timeout 请求超时（秒），可选，默认 10

规划与进度

公众号：基础能力已完成（OAuth/服务器/菜单/用户/素材/标签/JS-SDK 等）
小程序：基础能力已完成（登录/手机号/码/链接/内容安全/订阅消息/客服/物流/分析/版本等）
支付：基础能力已完成（支付下单/订单查询/退款/账单/回调处理等）
服务商：基础能力已完成（代子商户下单/订单查询/退款/进件/分账/转账/账单/小程序授权等）✨
服务器：基础能力已完成（消息处理/加密解密/多种回复类型/支付回调/物流回调等）

约定

所有 API 返回数组
统一抛出 CpWeixin\Core\Exceptions\WeixinException

p18 / cp_weixin

Maintainers

Details

README

安装

快速开始（公众号 OAuth）

微信扫码授权登录（PC网站）

公众号服务器（一键处理）

公众号 API 示例（菜单）

小程序示例（登录）

获取 UnionID（无需网页授权）

支付 JSAPI 示例

支付回调处理（一键处理）

小程序物流回调（一键处理）

模块方法列表

公众号 OAuth 模块

公众号服务器模块

公众号 API 模块

小程序模块

小程序物流回调模块

支付模块

支付下单

订单管理

退款管理

分账管理

转账管理

账单管理

证书与回调

服务商模块

服务商支付下单

服务商订单管理

服务商退款管理

子商户进件管理

子商户管理

服务商分账管理

服务商转账管理

服务商账单管理

服务商 JSAPI 配置

服务商小程序模块

小程序授权管理

服务商小程序支付

服务商小程序登录

配置项

规划与进度

约定