微信平台

微信公众平台、小程序和服务平台客户端共享“官方相对 path + 参数数组”的调用方式。SDK 管理协议和 token，不把官方接口复制成大量业务方法。

公众平台

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

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

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

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

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

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 统一捕获。

4.2 KiB Raw Permalink Blame History Unescape Escape