# cp_weixin

**Repository Path**: p87/cp_weixin

## Basic Information

- **Project Name**: cp_weixin
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-26
- **Last Updated**: 2026-01-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CP Weixin SDK

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

## 安装

```bash
composer require p18/cp_weixin
```

## 快速开始（公众号 OAuth）

```php
<?php

use CpWeixin\Weixin;

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

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

```php
<?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
<?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
<?php

use CpWeixin\Weixin;

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

## 小程序示例（登录）

```php
<?php

use CpWeixin\Weixin;

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

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

## 获取 UnionID（无需网页授权）

```php
<?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
<?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
<?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
<?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`