mirror of
https://gitee.com/zoujingli/WeChatDeveloper.git
synced 2026-09-04 23:12:09 +08:00
158 lines
4.2 KiB
Markdown
158 lines
4.2 KiB
Markdown
# 微信平台
|
||
|
||
微信公众平台、小程序和服务平台客户端共享“官方相对 path + 参数数组”的调用方式。SDK 管理协议和 token，不把官方接口复制成大量业务方法。
|
||
|
||
## 公众平台
|
||
|
||
```php
|
||
<?php
|
||
|
||
declare(strict_types=1);
|
||
|
||
use We\Client;
|
||
use We\Config\WechatPlatformConfig;
|
||
|
||
$platform = (new Client())->wechatPlatform(new WechatPlatformConfig(
|
||
appid: 'wx_appid',
|
||
appSecret: 'app_secret',
|
||
));
|
||
|
||
$users = $platform->get('cgi-bin/user/get', [
|
||
'next_openid' => '',
|
||
]);
|
||
|
||
$result = $platform->post('cgi-bin/message/custom/send', [
|
||
'touser' => 'openid',
|
||
'msgtype' => 'text',
|
||
'text' => ['content' => 'hello'],
|
||
]);
|
||
```
|
||
|
||
GET 的第二个参数作为 query；POST 的第二个参数默认作为 JSON body。`options` 可透传 Guzzle 的 `headers`、`timeout`、`query`、`body` 或 `form_params`。
|
||
|
||
网页授权等不需要公众号 access token 的接口应显式关闭 token：
|
||
|
||
```php
|
||
<?php
|
||
|
||
declare(strict_types=1);
|
||
|
||
$oauth = $platform->get('sns/oauth2/access_token', [
|
||
'appid' => 'wx_appid',
|
||
'secret' => 'app_secret',
|
||
'code' => 'authorization_code',
|
||
'grant_type' => 'authorization_code',
|
||
], [
|
||
'with_token' => false,
|
||
]);
|
||
```
|
||
|
||
## 小程序
|
||
|
||
```php
|
||
<?php
|
||
|
||
declare(strict_types=1);
|
||
|
||
use We\Client;
|
||
use We\Config\WechatWxappConfig;
|
||
|
||
$wxapp = (new Client())->wechatWxapp(new WechatWxappConfig(
|
||
appid: 'wx_appid',
|
||
appSecret: 'app_secret',
|
||
));
|
||
|
||
$session = $wxapp->get('sns/jscode2session', [
|
||
'appid' => 'wx_appid',
|
||
'secret' => 'app_secret',
|
||
'js_code' => 'login_code',
|
||
'grant_type' => 'authorization_code',
|
||
], [
|
||
'with_token' => false,
|
||
]);
|
||
```
|
||
|
||
## 原始响应、下载和上传
|
||
|
||
`raw()` 与 `download()` 返回 PSR-7 `ResponseInterface`，适用于图片、媒体和其他非 JSON 数据。`upload()` 接受 Guzzle multipart 结构并解析平台 JSON 响应。
|
||
|
||
```php
|
||
<?php
|
||
|
||
declare(strict_types=1);
|
||
|
||
$image = $platform->download('cgi-bin/media/get', [
|
||
'media_id' => 'MEDIA_ID',
|
||
]);
|
||
$binary = (string) $image->getBody();
|
||
|
||
$upload = $platform->upload('cgi-bin/media/upload', [
|
||
[
|
||
'name' => 'media',
|
||
'contents' => fopen(__DIR__ . '/demo.jpg', 'rb'),
|
||
'filename' => 'demo.jpg',
|
||
],
|
||
], [
|
||
'type' => 'image',
|
||
]);
|
||
```
|
||
|
||
所有通用微信平台 path 必须是相对路径。`https://...`、`http://...` 和 `//host/path` 都会被拒绝，避免把平台客户端放大为任意 URL 请求器。
|
||
|
||
## 消息安全模式
|
||
|
||
公众平台配置 `token` 和 `encodingAesKey` 后，可通过特殊操作名处理消息：
|
||
|
||
```php
|
||
<?php
|
||
|
||
declare(strict_types=1);
|
||
|
||
$plain = $platform->post('decrypt_message', [
|
||
'body' => $rawXml,
|
||
'msg_signature' => $messageSignature,
|
||
'timestamp' => $timestamp,
|
||
'nonce' => $nonce,
|
||
]);
|
||
|
||
$encrypted = $platform->post('encrypt_message', [
|
||
'body' => $replyXml,
|
||
'timestamp' => (string) time(),
|
||
'nonce' => $nonce,
|
||
]);
|
||
```
|
||
|
||
## 微信服务平台
|
||
|
||
服务平台客户端管理 component access token，并可代表授权方调用官方接口。授权方 refresh token 的持久化由业务系统实现 `StoreTokenInterface`。
|
||
|
||
```php
|
||
<?php
|
||
|
||
declare(strict_types=1);
|
||
|
||
use We\Client;
|
||
use We\Config\WechatServiceConfig;
|
||
|
||
$client = new Client(authorizers: $authorizerTokenStore);
|
||
$service = $client->wechatService(new WechatServiceConfig(
|
||
componentAppid: 'wx_component_appid',
|
||
componentAppSecret: 'component_secret',
|
||
componentToken: 'componentToken123',
|
||
componentEncodingAesKey: 'abcdefghijklmnopqrstuvwxyz0123456789ABCDEFG',
|
||
));
|
||
|
||
$componentToken = $service->componentAccessToken($componentVerifyTicket);
|
||
$preAuth = $service->createPreAuthCode($componentToken);
|
||
$url = $service->authorizationUrl(
|
||
(string) $preAuth['pre_auth_code'],
|
||
'https://example.com/wechat/component/callback',
|
||
);
|
||
```
|
||
|
||
通过通用 `get()`/`post()` 代表授权方调用时，在 options 中传 `authorizer_appid` 与 `component_access_token`。SDK 从 `StoreTokenInterface` 读取 refresh token，刷新后把完整 payload 回写业务存储。
|
||
|
||
## 返回与错误
|
||
|
||
JSON 调用成功时返回数组。微信平台业务错误、无效 JSON、凭证错误和传输错误抛出 `WechatException` 或 `ApiException`；签名错误抛出 `SignatureException`。它们都可由 `SdkException` 统一捕获。
|