README

这是一个简单的PHP库，用于与官方微信API交互。它被创建用来简化与微信API的交互。

use Garbetjie\WeChatClient\Client;
use Garbetjie\WeChatClient\Authentication;
 
$appID = 'Your app ID';
$secret = 'Your secret key';
 
try {
    $authService = new Authentication\Service(new Client());
    $client = $authService->authenticate($appID, $secret);
} catch (Authentication\Exception $e) {
    // Handle errors.
}

认证后，所有后续的API调用都将自动将访问令牌注入到请求中。

缓存访问令牌

在任何给定的一天，对于任何OA，可以获取的访问令牌数量有限。因此（以及性能原因），缓存这些访问令牌是个好主意。有几种存储机制可供选择来缓存访问令牌。

如果没有指定存储，则默认将访问令牌存储在sys_get_temp_dir()目录中的文件系统中。

文件系统

$cacheDirectory = '/tmp';
$storage = new \Garbetjie\WeChatClient\Authentication\Storage\File($cacheDirectory);

Memcached

$memcached = new \Memcached();
$memcached->addServer('127.0.0.1', 11211);
$keyPrefix = 'accessToken:';
 
$storage = new \Garbetjie\WeChatClient\Authentication\Storage\Memcached($memcached, $keyPrefix);

MySQL

$pdo = new PDO('mysql:host=127.0.0.1;dbname=mydb', 'root', '');
$tableName = '_wechat_tokens';
$columnMapping = [
    'token'   => 'token_column_name',
    'hash'    => 'hash_column_name',
    'expires' => 'expiry_column_name',
];

$storage = new \Garbetjie\WeChatClient\Authentication\Storage\MySQL($pdo, $tableName, $columnMapping);

MySQL存储适配器可以自定义表名以及列名。这可以确保访问令牌的存储符合您当前的数据库结构。

自定义接口

您可以编写任何您想存储访问令牌的自定义接口。任何这些自定义存储适配器都需要简单地实现Garbetjie\WeChatClient\Authentication\Storage\StorageInterface接口。

4. 群组

用户群组管理是通过Garbetjie\WeChatClient\Groups\Service进行的。为了查看和修改群组，需要认证。

$groupService = new \Garbetjie\WeChatClient\Groups\Service($client);

在通过API创建、修改或检索群组时，将返回Garbetjie\WeChatClient\Groups\Group实例。

创建一个群组

$group = $groupService->createGroup("Test group");

修改一个群组

$changedGroup = $group->withName('New test name');
$groupService->updateGroup($changedGroup);

删除一个群组

$groupService->deleteGroup($group);

获取所有群组。

$groups = $groupService->getAllGroups();
 
foreach ($groups as $group) {
    echo sprintf(
        "Group #%d with name `%s` has %d user(s)\n",
        $group->getID(),
        $group->getName(),
        $group->getUserCount()
    );
}

获取单个群组。

实际上，这是一个围绕Garbetjie\WeChatClient\Groups\GroupsService::getAllGroups()方法调用的薄包装，使得获取单个群组变得更容易。

$group = $groupService->getGroup(1);

5. 媒体

媒体项需要在微信的服务器上存储，才能作为消息发送给用户。可以使用Garbetjie\WeChatClient\Media\Service服务上传和下载媒体项。

创建一个新实例

$mediaService = new \Garbetjie\WeChatClient\Media\Service($client);

上传文件

use Garbetjie\WeChatClient\Media\Type;
 
$imageMediaItem = new Type\Image('/path/to/image.jpg');
$uploadedMediaItem = $mediaService->upload($imageMediaItem);
 
// $uploadedMediaItem now has its ID and upload data populated:
$uploadedMediaItem->getMediaID();
$uploadedMediaItem->getExpiresDate();

下载媒体项。

有3种方式下载媒体项

到一个文件（将路径作为$into参数传递）。

$mediaService->download($uploadedMediaItem->getMediaID(), '/path/to/downloaded.jpg');

到一个已打开的流（将流传递到$into参数）。

$fp = fopen('/tmp/downloaded.jpg', 'wb+');
$mediaService->download($uploadedMediaItem->getMediaID(), $fp);

或者将其输出到一个由 tmpfile() 函数创建的临时流中（对于 $into 参数不传递任何内容）。

$fp = $mediaService->download($uploadedMediaItem->getMediaID());
echo sprintf("Image is %d bytes in size", stream_get_length($fp));
fclose($fp);

支持的媒体类型

缩略图

上传新闻文章时必需。这里返回的媒体ID需要在添加新闻文章时使用。仅支持 JPG 图片，且大小不超过 64KB。

$thumbnailMediaItem = new \Garbetjie\WeChatclient\Media\Type\Thumbnail('/path/to/thumbnail.jpg');

新闻

当在广播消息中发送多故事新闻文章时使用。首先需要上传，发送广播消息时需要使用生成的消息ID。

use Garbetjie\WeChatClient\Media\Type;
 
$newsItem = new Type\NewsItem('Article title', 'Content of the article.', $thumbnailMediaItem->getMediaID());
$newsItem = $newsItem->withAuthor('Author name');
$newsItem = $newsItem->withURL('http://example.org');
$newsItem = $newsItem->withSummary('Short summary blurb.');
$newsItem = $newsItem->withImageShowing(true);
 
$news = (new Type\News())->withItem($newsItem);

音频

当向用户发送音频片段时使用。支持的类型是 AMR 和 MP3 音频文件，大小不超过 2MB。

$audioMessage = new \Garbetjie\WeChatClient\Media\Type\Audio('/path/to/item.mp3');

图片

用于向用户发送图片。支持 BMP、PNG、JPEG、JPG 或 GIF 扩展名，大小不超过 2MB。

$imageMessage = new \Garbetjie\WeChatClient\Media\Type\Image('/path/to/image.jpg');

视频

向用户发送视频。支持 MP4 格式，大小不超过 10MB。

$videoMediaItem = new \Garbetjie\WeChatClient\Media\Type\Video('/path/to/video.mp4');

6. 菜单

可以在微信API中自定义显示在官方账号中的菜单。通过 Garbetjie\WeChatClient\Menu\MenuService 服务可以修改此菜单

$menuService = new \Garbetjie\WeChatClient\Menu\Service($client);

7. 二维码

可以通过微信API生成二维码。有两种类型的二维码可供选择：临时二维码和永久二维码。

临时二维码在开发者指定的时长后过期（最长为 30 天），而永久二维码永不过期。然而，官方账号在任何时候都限制有 10 万个活动状态的永久二维码。

$qrService = new \Garbetjie\WeChatClient\QR\Service($client);

创建临时二维码

创建临时二维码时，您限于 1 到 100,000 的二维码值。如果没有指定过期时间，生成的二维码将在 30 秒后过期。您可以指定最多 2,592,000 秒（30 天）的过期时间。

use Garbetjie\WeChatClient\QR;
 
$service = new QR\Service($client);
$temporaryCode1 = $service->createTemporaryCode(1000, 3600); // Expires in an hour.
$temporaryCode2 = $service->createTemporaryCode(1001); // Expires in 30 seconds.
$temporaryCode3 = $service->createTemporaryCode(1002, 2592000); // Expires in 30 days.

创建永久二维码

永久二维码数量限制为 100,000 个，且没有过期日期。您可以使用 1 到 100,000 范围内的数字值，或者使用最多 64 个字符的字符串值。

use Garbetjie\WeChatClient\QR;
 
$service = new QR\Service($client);
$permanentCode = $service->createPermanentCode(1000);
// OR
$permanentCode = $service->createPermanentCode('Look at me');

术语

OA

官方账号。这基本上是客户端的响应者。

User

微信用户。也称为粉丝，这是通过手机设备、桌面应用程序或网络界面访问 OA 的最终用户。

回调消息

对粉丝发送的关键词的即时响应（以 XML 格式）。如果不能保证在 5 秒内回复，则应返回空响应（如 die()），并发送客服（推送）消息。

客服（推送）消息

也称为推送消息，这是 OA 对用户的异步响应。推送消息只能在用户与 OA 互动后的 48 小时内发送。

garbetjie / wechat

维护者

详细信息