From e19ac17d12e38f1d38037403c661ec751e4c8176 Mon Sep 17 00:00:00 2001 From: overtrue Date: Fri, 24 Apr 2015 04:06:25 +0800 Subject: [PATCH] =?UTF-8?q?=E6=B7=BB=E5=8A=A02.0=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Home.md | 6 +- JSSDK.md | 44 +++++++++ 二维码.md | 53 +++++++++++ 升级日志.md | 11 +++ 多客服的消息转发.md | 20 ++-- 安装.md | 7 +- 客服管理与发送消息.md | 44 +++++---- 接收消息与回复.md | 43 +++++++-- 消息的使用.md | 34 ++++--- 用户与用户组管理.md | 39 ++++++-- 监听微信事件.md | 53 ++++++++--- 短链接.md | 30 ++++++ 签名计算.md | 18 ---- 素材管理.md | 88 ++++++++++++++++++ 网页授权.md | 72 +++++++++++++-- 自定义缓存.md | 14 ++- 自定义菜单.md | 209 ++++++++++++++++++++++++++++++++++++++++-- 获取JSSDK的Ticket.md | 6 -- 配置与初始化.md | 55 +++++++---- 错误处理.md | 19 ++-- 20 files changed, 718 insertions(+), 147 deletions(-) create mode 100644 JSSDK.md create mode 100644 二维码.md create mode 100644 升级日志.md create mode 100644 短链接.md delete mode 100644 签名计算.md create mode 100644 素材管理.md delete mode 100644 获取JSSDK的Ticket.md diff --git a/Home.md b/Home.md index 8da991b..6d3ea56 100644 --- a/Home.md +++ b/Home.md @@ -1,4 +1,6 @@ +微信 SDK 2.0 文档 + - 基本使用 + [安装](安装) + [配置与初始化](配置与初始化) @@ -10,9 +12,11 @@ + [多客服的消息转发](多客服的消息转发) + [网页授权](网页授权) + [自定义菜单](自定义菜单) + + [JSSDK](JSSDK) + + [二维码](二维码) + + [短链接](短链接) - 其它 + [错误处理](错误处理) + [自定义缓存](自定义缓存) - + [签名计算](签名计算) + [获取JSSDK的Ticket](获取JSSDK的Ticket) \ No newline at end of file diff --git a/JSSDK.md b/JSSDK.md new file mode 100644 index 0000000..48c1381 --- /dev/null +++ b/JSSDK.md @@ -0,0 +1,44 @@ +本 SDK 同样由 `Overtrue\Wechat\Js` 提供了 JSSDK 相关的功能。 + +### 获取实例 + +```php +config(array $APIs, $debug = false, $json = false);` 获取JSSDK的配置数组，当 `$json` 为 `true` 时返回 JSON 格式字符串，你可以直接使用到网页中 +- `$js->setUrl($url)` 设置当前URL，如果不想用默认读取的URL，可以使用此方法手动设置，通常不需要。 + +example: + +我们可以生成js配置文件： + +```js + + +``` +结果如下： + +```js + + +``` \ No newline at end of file diff --git a/二维码.md b/二维码.md new file mode 100644 index 0000000..abe0ef6 --- /dev/null +++ b/二维码.md @@ -0,0 +1,53 @@ +本 SDK 由 `Overtrue\Wechat\QRCode` 提供微信二维码创建与获取等服务。 + +目前有2种类型的二维码： + +1. 临时二维码，是有过期时间的，最长可以设置为在二维码生成后的7天（即604800秒）后过期，但能够生成较多数量。临时二维码主要用于帐号绑定等不要求二维码永久保存的业务场景 +2. 永久二维码，是无过期时间的，但数量较少（目前为最多10万个）。永久二维码主要用于适用于帐号绑定、用户来源统计等场景。 + +### 获取实例 + +```php +show($qrTicket); ?>">`； ++ `void download($ticket, $filename)` 下载二维码到本地，`$filename` 为带文件名的目标路径； + +example: + +创建临时二维码: + +```php +$result = $qrcode->temporary(56, 6 * 24 * 3600); + +$ticket = $result->ticket;// 或者 $result['ticket'] +$expireSeconds = $result->expire_seconds; // 有效秒数 +$url = $result->url; // 二维码图片解析后的地址，开发者可根据该地址自行生成需要的二维码图片 +``` + +创建永久二维码: + +```php +$result = $qrcode->forever(56);// 或者 $qrcode->forever("56", self::SCENE_QR_FOREVER_STR); + +$ticket = $result->ticket; // 或者 $result['ticket'] +$url = $result->url; +``` +下载二维码到本地： + +```php +$qrcode->download($ticket, __DIR__ . '/code.jpg'); +``` diff --git a/升级日志.md b/升级日志.md new file mode 100644 index 0000000..7f29f8f --- /dev/null +++ b/升级日志.md @@ -0,0 +1,11 @@ +# 2.0 +- 【删除】移除 `Overtrue\Wechat\Wechat` 基类，便于处理多用户，各业务分散到独立的类中完成； +- 【删除】移除 `Menu::make()` 方法，改为 `new MenuItem($name, $type, $key)` 形式； +- 【新增】JSSDK 服务； +- 【新增】二维码服务； +- 【新增】异常消息添加中文错误消息； +- 【新增】门店服务； +- 【新增】素材添加完整 API 支持，支持永久素材等官方提供的所有功能； +- 【变更】消息中图片等附件不再自动上传，之前 `media($path)` 不再接受本地文件路径，只接受上传后的 `media_id` 值，上传请先使用素材管理服务进行上传，便于素材管理； +- 【变更】 `Wechat::service('cache')` 同样不存在了，更改为 new 服务(...), ex: `$userService = new Overtrue\Wechat\User($appId, $secret)`； +- 【变更】 之前服务里的 `->all()` 方法均改名为 `->lists()`； diff --git a/多客服的消息转发.md b/多客服的消息转发.md index 3baba0a..993df47 100644 --- a/多客服的消息转发.md +++ b/多客服的消息转发.md @@ -1,15 +1,15 @@ -多客服的消息转发绝对是超级的简单： +多客服的消息转发绝对是超级的简单，转发的消息类型为 `transfer`： ```php - use Overtrue\Wechat\Services\Message; - + use Overtrue\Wechat\Message; + // 转发收到的消息给客服 - $wechat->on('message', function($message) { - return Message::make('transfer'); + $server->on('message', function($message) { + return Message::make('transfer'); }); - $result = $wechat->serve(); + $result = $server->serve(); echo $result; ``` @@ -17,7 +17,9 @@ 当然，你也可以指定转发给某一个客服： ```php -return Message::make('transfer')->account($account); +return Message::make('transfer')->account($account); // 或者 -return Message::make('transfer')->to($account); -``` \ No newline at end of file +return Message::make('transfer')->to($account); +``` + +更多关于多客服消息转发：http://mp.weixin.qq.com/wiki/5/ae230189c9bd07a6b221f48619aeef35.html \ No newline at end of file diff --git a/安装.md b/安装.md index 4bc6c38..e53719c 100644 --- a/安装.md +++ b/安装.md @@ -11,12 +11,11 @@ 下载[最新版zip包](https://github.com/overtrue/wechat/archive/master.zip) 或者下载指定版本:https://github.com/overtrue/wechat/releases 然后引入根目录的autoload.php即可： - + ```php staff; - ``` +本 SDK 由 `Overtrue\Wechat\Staff` 提供客服相关服务。 -+ `$staff->all();` 获取所有客服账号 -+ `$staff->allOnline();` 获取所有在线的客服账号 -+ `$staff->create($mail, $nickname, $password);` 添加客服帐号 -+ `$staff->update($mail, $nickname, $password);` 修改客服帐号 -+ `$staff->delete($mail, $nickname, $password);` 删除客服帐号 -+ `$staff->avatar($mail, $avatarPath);` 设置客服帐号的头像 + + +### 获取实例 + +```php +lists();` 获取所有客服账号列表 ++ `$staff->onlines();` 获取所有在线的客服账号列表 ++ `$staff->create($email, $nickname, $password);` 添加客服帐号 ++ `$staff->update($email, $nickname, $password);` 修改客服帐号 ++ `$staff->delete($email, $nickname, $password);` 删除客服帐号 ++ `$staff->avatar($email, $avatarPath);` 设置客服帐号的头像 + `$staff->send($message)->to($openId);` 主动发送消息给用户 -+ 群发消息 ++ `$staff->send($message)->by('account@test')->to($openId);` 指定客服发送消息 - ```php - // 所有人 - $staff->send($message)->toAll(); - // 指定组 - $staff->send($message)->toGroup($groupId); - // 多个人 - $staff->send($message)->toThem(array($openId, $openId, ...)); - ``` +关于更多客服接口信息请参考微信官方文档：http://mp.weixin.qq.com/wiki/9/6fff6f191ef92c126b043ada035cc935.html diff --git a/接收消息与回复.md b/接收消息与回复.md index 79dba03..0f8728e 100644 --- a/接收消息与回复.md +++ b/接收消息与回复.md @@ -1,12 +1,31 @@ 消息的监听再简单不过了，你不需要像其它SDK一样麻烦，这将会是前所未有的简单，你可以选择监听所有类型或者指定某种类型，以及作出相应的响应，比如回复一条应答消息。 +在本 SDK 中，服务端的操作，例如：服务器认证，监听事件，接收用户消息等所有微信向我们自有服务器发起请求的，都交由 `Overtrue\Wechat\Server` 来处理。 + +### 获取服务端实例 + +```php +on('message', callable $callback); // 全部类型 -// or +// or $wechat->on('message', string $messageType, callable $callback); // 只监听指定类型 ``` - -参数说明 + +#### 参数说明： - `$messageType` string, 指定要处理的消息类型，ex：`image` - `$callback` callable, 回调函数，closure匿名函数，或者一切可调用的方法或者函数 @@ -14,20 +33,30 @@ $wechat->on('message', string $messageType, callable $callback); // 只监听指 example: ```php +on('message', function($message) { +$server->on('message', function($message) { return Message::make('text')->content('您好！'); }); // 监听指定类型 -$wechat->on('message', 'image', function($message) { +$server->on('message', 'image', function($message) { return Message::make('text')->content('我们已经收到您发送的图片！'); }); -$result = $wechat->serve(); +$result = $server->serve(); echo $result; ``` diff --git a/消息的使用.md b/消息的使用.md index ce4b6a2..015a7ec 100644 --- a/消息的使用.md +++ b/消息的使用.md @@ -5,10 +5,10 @@ | 消息类型 | 类型名称 | 属性 | 除属性自身外提供的方法 | |----------|----------|----------------------------------------------------------------------------------|-------------------------------------------| | 文本 | `text` | `content` 内容 | | -| 图片 | `image` | `media_id` 媒体资源id | `media($path)` | -| 声音 | `voice` | `media_id` 媒体资源id | `media($path)` | -| 音乐 | `music` | `title` 标题
`description` 描述
`url` 音乐URL
`hq_url` 高清URL
`thumb_media_id` 封面资源id | `thumb($path)` | -| 视频 | `video` | `title` 标题
`description` 描述
`media_id` 媒体资源id
`thumb_media_id` 封面资源id | `media($path)`
`thumb($path)` | +| 图片 | `image` | `media_id` 媒体资源id | `media($mediaId)` | +| 声音 | `voice` | `media_id` 媒体资源id | `media($mediaId)` | +| 音乐 | `music` | `title` 标题
`description` 描述
`url` 音乐URL
`hq_url` 高清URL
`thumb_media_id` 封面资源id | `thumb($mediaId)` | +| 视频 | `video` | `title` 标题
`description` 描述
`media_id` 媒体资源id
`thumb_media_id` 封面资源id | `media($mediaId)`
`thumb($mediaId)` | | 位置 | `location` | `lat` 地理位置纬度
`lon` 地理位置经度
`scale` 地图缩放大小
`label` 地理位置信息 | | | 链接 | `link` | `title` 标题
`description` 描述
url 链接URL | | @@ -33,21 +33,25 @@ $wechat->on('event', 'subscribe', function($event){ 这里有一点需要注意，当属性带下划线的时候，方法名是支持两种的：`media_id()` 或者 `mediaId()` 都一样。 -### 上传媒体文件 - +### 上传素材文件 ```php -$message = Message::make('image')->media('D:/test/demo.jpg'); +image(__DIR__ . '/demo.jpg'); // 上传并返回媒体ID + +$message = Message::make('image')->media($imageId); ``` -媒体文件你不用上传，也就是说media_id是我来维护，你直接传本地文件就好了。 -方法`media($file)`会上传文件然后赋值到`media_id`属性。如果想要获取上传后的media_id: +> 请注意：方法`media($mediaId)`会直接赋值到`media_id`属性。不会自动上传文件。1.x 版本是会自动上传的，2.x 已经不再提供。 -```php -$mediaId = $message->media_id; -``` +#### 这里有两个方法用于设置素材ID： -#### 这里有两个方法用于设置媒体文件： +- `media($mediaId)` 对应设置 `media_id` +- `thumb($mediaId)` 对应设置 `thumb_media_id` -- `media($file)` 对应设置 `media_id` -- `thumb($file)` 对应设置 `thumb_media_id` \ No newline at end of file +关于更多素材管理请参考：[素材管理](素材管理) \ No newline at end of file diff --git a/用户与用户组管理.md b/用户与用户组管理.md index 068fb5a..fe30445 100644 --- a/用户与用户组管理.md +++ b/用户与用户组管理.md @@ -1,12 +1,24 @@ -## 用户 +本 SDK 中上传素材通过 `Overtrue\Wechat\User`、`Overtrue\Wechat\Group` 提供用户与用户组管理服务。 - ```php - $userService = $wechat->user; - ``` +### 获取实例 + +```php +get($openId);` 获取用户信息 -+ `$userService->all($nextOpenId = null);` 获取用户列表, $nextOpenId 可选 ++ `$userService->lists($nextOpenId = null);` 获取用户列表, $nextOpenId 可选 + `$userService->remark($openId, $remark);` 修改用户备注, 返回boolean ++ `$userService->group($openId);` 获取用户所属用户组ID example: @@ -16,13 +28,20 @@ $user = $userService->get($openId); echo $user->nickname; ``` -## 用户组 +## 用户组 - ```php - $group = $wechat->group; - ``` +```php +all();` 获取所有分组 +use Overtrue\Wechat\User; + +$appId = 'wx3cf0f39249eb0e60'; +$secret = 'f1c242f4f28f735d4687abb469072a29'; + +$group = new Group($appId, $secret); +``` + ++ `$group->lists();` 获取所有分组 + `$group->update($groupId, $name);` 修改分组信息 + `$group->moveUser($openId, $groupId);` 移动单个用户到指定分组 + `$group->moveUsers(array $openIds, $groupId);` 批量移动用户到指定分组 \ No newline at end of file diff --git a/监听微信事件.md b/监听微信事件.md index 8ad9eb0..13d3f64 100644 --- a/监听微信事件.md +++ b/监听微信事件.md @@ -1,37 +1,64 @@ 所有的事件都可以很方便的监听与处理，与监听消息一样，同样支持监听全部类型或者指定类型。 关于事件类型请参考微信官方文档：http://mp.weixin.qq.com/wiki/2/5baf56ce4947d35003b86a9805634b1e.html +在本 SDK 中，服务端的操作，例如：服务器认证，监听事件，接收用户消息等所有微信向我们自有服务器发起请求的，都交由 `Overtrue\Wechat\Server` 来处理。 + +### 获取服务端实例 + ```php -$wechat->on('event', callable $callback); -// or -$wechat->on('event', string $eventType, callable $callback); +on('event', callable $callback); +// or +$server->on('event', string $eventType, callable $callback); +``` + +#### 参数说明： - `$eventType` string, 指定要处理的消息类型，ex：`image` - `$callback` callable, 回调函数，closure匿名函数，或者一切可调用的方法或者函数 -example: +完整举例: ```php +on('event', function($event) { - error_log('收到取消关注事件，取消关注者openid: ' . $event['FromUserName']); +$server->on('event', function($event) { + error_log('收到取消关注事件，取消关注者openid: ' . $event['FromUserName']); }); // 只监听指定类型事件 -$wechat->on('event', 'subscribe', function($event) { +$server->on('event', 'subscribe', function($event) { - error_log('收到关注事件，关注者openid: ' . $event['FromUserName']); + error_log('收到关注事件，关注者openid: ' . $event['FromUserName']); return Message::make('text')->content('感谢您关注'); }); -$result = $wechat->serve(); - -echo $result; +$res = $server->serve(); +echo $res; // or return $res; 在某些框架中需要返回字符串 ``` diff --git a/短链接.md b/短链接.md new file mode 100644 index 0000000..32fe7d6 --- /dev/null +++ b/短链接.md @@ -0,0 +1,30 @@ +本 SDK 由 `Overtrue\Wechat\Url` 提供微信链接转换服务。 + +主要使用场景： 开发者用于生成二维码的原链接（商品、支付二维码等）太长导致扫码速度和成功率下降，将原长链接通过此接口转成短链接再生成二维码将大大提升扫码速度和成功率。 + +### 获取实例 + +```php +short('http://overtrue.me/open-source'); +// +``` + +微信官方文档：http://mp.weixin.qq.com/wiki/10/165c9b15eddcfbd8699ac12b0bd89ae6.html \ No newline at end of file diff --git a/签名计算.md b/签名计算.md deleted file mode 100644 index 8500e5a..0000000 --- a/签名计算.md +++ /dev/null @@ -1,18 +0,0 @@ -Wechat基类提供了计算签名的方法： - -```php - $wechat->signature($params); -``` - -example: - -```php -$params = array( - 'token' => 'mock_token', - 'time' => time(), - 'nonce' => 'hello', - ); - -$signature = $wechat->signature($params); -// 313f67a0d1af958128c6761230fa1f1282ed027e -``` diff --git a/素材管理.md b/素材管理.md new file mode 100644 index 0000000..1eaaac8 --- /dev/null +++ b/素材管理.md @@ -0,0 +1,88 @@ +在微信里的图片，音乐，视频等等都需要先上传到微信服务器作为素材才可以在消息中使用。 + +> 请注意： + 1. 限制： + - 图片（image）: 1M，支持 bmp/png/jpeg/jpg/gif 格式 + - 语音（voice）：2M，播放长度不超过 60s，支持 mp3/wma/wav/amr 格式 + - 视频（video）：10MB，支持MP4格式 + - 缩略图（thumb）：64KB，支持JPG格式 + 2. `media_id` 是可复用的； + 3. 素材分为 `临时素材` 与 `永久素材`， 临时素材媒体文件在后台保存时间为3天，即 3 天后 `media_id` 失效； + 4. 新增的永久素材也可以在公众平台官网素材管理模块中看到； + 5. 永久素材的数量是有上限的，请谨慎新增。图文消息素材和图片素材的上限为5000，其他类型为1000； + +本 SDK 中上传素材通过 `Overtrue\Wechat\Media` 提供素材管理服务。 + +### 获取实例 + +```php +image($path);`, 上传临时图片； +- `$media->voice($path);`, 上传临时声音； +- `$media->video($path, $title, $description);`, 上传临时视频； +- `$media->thumb($path);`, 上传临时缩略图，用于视频封面或者音乐封面； +- `$media->news(array $articles);`, 上传永久图文消息，图文没有临时； +- `$media->updateNews($mediaId, array $article, $index);`, 修改永久图文消息，要更新的文章在图文消息中的位置（多图文消息时，此字段才有意义，单图片忽略此参数），第一篇为0； +- `$media->forever()->image($path);` 上传永久图片； +- `$media->forever()->voice($path);` 上传永久声音； +- `$media->forever()->video($path);` 上传永久视频； +- `$media->forever()->thumb($path);` 上传永久缩略图； +- `$media->lists($type, $offset, $count);` 获取永久素材列表，参考：[微信公众平台开发者文档：获取永久素材列表](http://mp.weixin.qq.com/wiki/12/2108cd7aafff7f388f41f37efa710204.html) +- `$media->stats($type = null);` 获取素材计数，不指定 `$type` 则返回全部 +- `$media->delete($mediaId);` 删除永久素材； +- `$media->download($mediaId, $filename);` 下载临时素材到本地，`$filename` 为目标路径带文件名，例如：`$media->download($mediaId, __DIR__ . '/test.jpg');`； +- `$media->forever()->download($mediaId, $filename);` 下载永久素材到本地； + +> 上传永久图文消息 `$articles` 结构为： + + [{ + "title": TITLE, + "thumb_media_id": THUMB_MEDIA_ID, + "author": AUTHOR, + "digest": DIGEST, + "show_cover_pic": SHOW_COVER_PIC(0 / 1), + "content": CONTENT, + "content_source_url": CONTENT_SOURCE_URL + }, + //若新增的是多图文素材，则此处应还有几段articles结构 + ] + +字段说明： + + - title: 标题 + - thumb_media_i: 图文消息的封面图片素材id（必须是永久mediaID） + - autho: 作者 + - diges: 图文消息的摘要，仅有单图文消息才有摘要，多图文此处为空 + - show_cover_pic: 是否显示封面，0为false，即不显示，1为true，即显示 + - content: 图文消息的具体内容，支持HTML标签，必须少于2万字符，小于1M，且此处会去除JS + - content_source_ur: 图文消息的原文地址，即点击“阅读原文”后的URL + +### 示例： + +创建图片消息： + +```php +image(__DIR__ . '/demo.jpg'); // 上传并返回媒体ID + +$message = Message::make('image')->media($imageId); +``` + +更多请参考官方文档：http://mp.weixin.qq.com/wiki/home/index.html `素材管理` 章节 \ No newline at end of file diff --git a/网页授权.md b/网页授权.md index 53a4bc5..9f8024f 100644 --- a/网页授权.md +++ b/网页授权.md @@ -1,24 +1,78 @@ - ```php - $wechat->auth; - ``` +网页授权在本 SDK 中由 `Overtrue\Wechat\Auth` 提供服务。 + + +```php +auth->url($to, $state, $scope); + $auth->url($to, $scope, $state = 'STATE'); // 直接跳转 - $wechat->auth->redirect($to, $state, $scope); 直接跳转 + $auth->redirect($to, $scope, $state = 'STATE'); 直接跳转 ``` +> 注意： +- 上面的 $scope 与 $state 通常都不用传 +- `url` 与 `redirect` 参数一致 +- $scope 可选为： + + snsapi_base 只获取用户 `openid` + + snsapi_userinfo 获取用户账号信息 + +example: + +```php +// 只取 `openid` +$url = $auth->url('http://overtrue.me', 'snsapi_base'); +// 需要拉取用户信息 +$url = $auth->url('http://overtrue.me', 'snsapi_userinfo'); +``` + + 判断是否已经授权 ```php - $wechat->auth->authorized(); + $auth->authorized(); ``` -+ 获取授权用户 ++ 获取已授权用户 ```php - $wechat->auth->user(); - ``` \ No newline at end of file + $auth->user(); + ``` + +## 示例： + +```php +// 如果已经授权或者 SESSION 未过期 +if ($auth->authorized() || Session::get('logged_open_id')) { + $user = $auth->user();// 获取已经登录后用户信息 + Session::set('logged_open_id', $user['open_id']); + + //code 显示授权后的页面，或者跳转到其它授权才能访问的页面 + //... +} else { + $to = "http://微信授权完成后跳回你的地址，就是当前代码所在的 URL"; + $auth->redirect($to); +} +``` + +### 在 [Laravel](http://laravel.com) 里使用 + +在 Laravel 里的跳转请使用 `url` 而不要使用 `redirect`, 因为在 Laravel 控制器方法必须返回字符串或者实现了 `__toString()` 的对象： + +```php +return Redirect::to($auth->url($to, 'snsapi_base', 'STATE')); +``` + +更多关于微信网页授权 API 请参考： http://mp.weixin.qq.com/wiki/17/c0f37d5704f0b64713d5d2c37b468d75.html \ No newline at end of file diff --git a/自定义缓存.md b/自定义缓存.md index 0179d2f..7362420 100644 --- a/自定义缓存.md +++ b/自定义缓存.md @@ -1,17 +1,23 @@ -微信的access_token是不能太频繁的调用的，所以需要缓存，本SDK默认使用文件缓存，文件会创建在代码运行环境的临时目录里，使用[sys_get_temp_dir()](http://php.net/manual/zh/function.sys-get-temp-dir.php) 函数获取的临时目录下。 +微信的 `access_token` 是不能太频繁的调用的，所以需要缓存，本 SDK 默认使用文件缓存，文件会创建在代码运行环境的临时目录里，使用[sys_get_temp_dir()](http://php.net/manual/zh/function.sys-get-temp-dir.php) 函数获取的临时目录下。 如果你需要自定义缓存方式，那么Wechat提供了以下两个方法： ```php +cache->setter(function($key, $value, $lifetime){ +Cache::setter(function($key, $value, $lifetime){ return your_custom_set_cache($key, $value, $lifetime); }); // 读取 -$wechat->cache->getter(function($key){ +Cache::getter(function($key){ return your_custom_get_cache($key); }); ``` -当你的`getter` 没有返回缓存的值时，会重新请求access_token。 \ No newline at end of file +`your_custom_set_cache` 为你自己的方法，这里是举例。 + +当你的 `getter` 没有返回缓存的值时，会重新请求 `access_token`。 \ No newline at end of file diff --git a/自定义菜单.md b/自定义菜单.md index 8c02fb2..3a3b48e 100644 --- a/自定义菜单.md +++ b/自定义菜单.md @@ -1,9 +1,204 @@ - ```php - $wechat->menu; - ``` +本 SDK 由 `Overtrue\Wechat\Menu` 与 `Overtrue\Wechat\MenuItem` 提供微信菜单的管理服务。 -+ `$menu->get();` 读取菜单 -+ `$menu->set($menus);` 设置菜单 -+ `$menu->delete();` 删除菜单 +自定义菜单功能的使用场景：你自己做了网站后台，想要管理某个公众号的菜单，在后台填写表单后，经由 SDK 请求微信的服务器完成菜单设定。 -> 待补充... \ No newline at end of file +## 概念 + +#### 菜单项 `MenuItem` + +菜单的组成单位，分为一级与二级，一个微信菜单包含最多3个一级菜单项。一个一级菜单项可以包含最多5个二级菜单项。 + + +## 注意事项 + +目前自定义菜单最多包括3个一级菜单，每个一级菜单最多包含5个二级菜单。一级菜单最多4个汉字，二级菜单最多7个汉字，多出来的部分将会以“...”代替。请注意，创建自定义菜单后，由于微信客户端缓存，需要24小时微信客户端才会展现出来。建议测试时可以尝试取消关注公众账号后再次关注，则可以看到创建后的效果。 + +### 获取实例 + +```php +get();` 读取菜单 ++ `boolean $menu->set(array $menus);` 设置菜单，参数为一个包含最多三个一级菜单项的数组 ++ `boolean $menu->delete();` 删除菜单 ++ `new MenuItem($name, $type = null, $key = null)` 创建一个菜单项 + - `$name` 菜单项名称，比如：`今日歌曲` + - `$type` 菜单项类型，比如：`view`,`click`等，更多请参考 http://mp.weixin.qq.com/wiki `自定义菜单` 章节。 + - `$key` 菜单项的值，当 `$type` 为 `view` 时为目标 URL，其它为自定义 key。 + +一个菜单项可以使用 `buttons` 方法传入一个菜单项数组创建二级菜单项: + +`` + +> 注意：由于微信客户端缓存，需要24小时微信客户端才会展现出来。建议测试时可以尝试取消关注公众账号后再次关注，则可以看到创建后的效果。 + +example: + +```php + +$button = new MenuItem("菜单"); + +$menus = array( + new MenuItem("今日歌曲", 'click', 'V1001_TODAY_MUSIC'), + $button->buttons(array( + new MenuItem('搜索', 'view', 'http://www.soso.com/'), + new MenuItem('视频', 'view', 'http://v.qq.com/'), + new MenuItem('赞一下我们', 'click', 'V1001_GOOD'), + )), + ); + +try { + $menu->set($menus);// 请求微信服务器 + echo '设置成功！'; +} catch (\Exception $e) { + echo '设置失败：' . $e->getMessage(); +} + +``` + +生成结果： + +```json + { + "button":[ + { + "type":"click", + "name":"今日歌曲", + "key":"V1001_TODAY_MUSIC" + }, + { + "name":"菜单", + "sub_button":[ + { + "type":"view", + "name":"搜索", + "url":"http://www.soso.com/" + }, + { + "type":"view", + "name":"视频", + "url":"http://v.qq.com/" + }, + { + "type":"click", + "name":"赞一下我们", + "key":"V1001_GOOD" + }] + }] + } +``` + +### 创建子菜单 + +`Overtrue\Wechat\MenuItem` 对象有一个方法 `buttons(array $items)` 指定**二级菜单**(子菜单)。 + +```php +$button = new MenuItem('菜单'); +$button->buttons(array( + new MenuItem('搜索', 'view', 'http://www.soso.com/'), + new MenuItem('视频', 'view', 'http://v.qq.com/'), + new MenuItem('赞一下我们', 'click', 'V1001_GOOD'), + )); + +``` + +以上就会构成以下样子的菜单： + +``` +菜单 + 搜索 + 视频 + 赞一下我们 +``` + +## Laravel 示例 + +输入菜单数组（从你的网站后台表单创建）： +```json +[ + { + "name":"博客", + "type":"view", + "key" :"http://overtrue.me" + }, + { + "name": "更多", + "type": null, + "key": null, + "buttons":[ + { + "name":"GitHub", + "type":"view", + "key" :"https://github.com/overtrue" + }, + { + "name":"微博", + "type":"view", + "key" :"http://weibo.com/44294631" + } + ] + } +] +``` + +控制器示例： + +```php +buttons($buttons); + } + + $target[] = $item; + } + + $menu->set($target); // 失败会抛出异常 + + return Redirect::back()->withMessage('菜单设置成功！'); + } + //... +} + +``` + +更多关于微信自定义菜单 API 请参考： http://mp.weixin.qq.com/wiki `自定义菜单` 章节。 \ No newline at end of file diff --git a/获取JSSDK的Ticket.md b/获取JSSDK的Ticket.md deleted file mode 100644 index 955cabb..0000000 --- a/获取JSSDK的Ticket.md +++ /dev/null @@ -1,6 +0,0 @@ -```php -$wechat->ticket->js(); -$wechat->ticket->card(); -``` - -> 待补充 \ No newline at end of file diff --git a/配置与初始化.md b/配置与初始化.md index b6e63bc..9b3181f 100644 --- a/配置与初始化.md +++ b/配置与初始化.md @@ -1,26 +1,43 @@ -本项目的用法目前网上其它SDK用法不同，这里只需要像下面这样配置一次完成： +本项目中提供了很多服务，每个服务需要的初始化参数可能会有不同： -```php - 'Your app id', - 'secret' => 'Your secret' - 'token' => 'Your token', - 'encodingAESKey' => 'Your encoding AES Key' // optional -]; +### 用户 +- 类名：`Overtrue\Wechat\User` +- 初始化参数：`__construct($appId, $appSecret)` -$wechat = Wechat::make($options); +### 用户组 +- 类名：`Overtrue\Wechat\Group` +- 初始化参数：`__construct($appId, $appSecret)` -$server = $wechat->on('message', function($message){ - error_log("收到来自'{$message['FromUserName']}'的消息：" . $message['Content']); -}); +### 菜单 +- 类名：`Overtrue\Wechat\Menu` +- 初始化参数：`__construct($appId, $appSecret)` -$result = $wechat->serve(); +### JSSDK +- 类名：`Overtrue\Wechat\Menu` +- 初始化参数：`__construct($appId, $appSecret)` -// 您可以直接echo 或者返回给框架 -echo $result; -``` -`$wechat->serve()` 方法返回的值为字符串或者空，用于应答微信服务器的推送，消息或者事件等。比如你如果使用的是Laravel,你这里就应该 `return $wechat->serve();` \ No newline at end of file +### 客服 +- 类名：`Overtrue\Wechat\Staff` +- 初始化参数：`__construct($appId, $appSecret)` + +### 门店 +- 类名：`Overtrue\Wechat\Store` +- 初始化参数：`__construct($appId, $appSecret)` + +### 二维码 +- 类名：`Overtrue\Wechat\QRCode` +- 初始化参数：`__construct($appId, $appSecret)` + +### 素材 +- 类名：`Overtrue\Wechat\Media` +- 初始化参数：`__construct($appId, $appSecret)` + +请在使用中不要忘记引入命名空间。关于命名空间的使用：[PHP官方文档](http://php.net/manual/zh/language.namespaces.php) \ No newline at end of file diff --git a/错误处理.md b/错误处理.md index d7c84ef..2feff01 100644 --- a/错误处理.md +++ b/错误处理.md @@ -1,15 +1,20 @@ -所有的错误均使用异常抛出 +所有的错误均使用异常抛出，异常类名为 `Overtrue\Wechat\Exception`, 你可以使用常规的异常处理方法来处理本 SDK 所有的异常： + +比如使用 `[set_exception_handler](http://php.net/manual/zh/function.set-exception-handler.php)`: ```php - $wechat->error(function($error){ - error_log("code:" . $error->getCode . ' error: ' . $error->getMessage()); + set_exception_handler(function($exception){ + error_log("code:" . $exception->getCode . ' exception: ' . $exception->getMessage()); }); ``` -这里的回调函数的第一个参数为继承自Exception的异常类，所以你可以使用Exception的所有方法。 +这里的回调函数的第一个参数为继承自 `[Exception](http://php.net/manual/zh/class.exception.php)` 的异常类，所以你可以使用 [Exception](http://php.net/manual/zh/class.exception.php) 的所有方法。 -- `$error->getCode()` 错误码，ex: `40001` -- `$error->getMessage()` 错误消息 -- `$error->getLine()` 错误行（当然这个没啥意义） +- `$exception->getCode()` 错误码，ex: `40001` +- `$exception->getMessage()` 错误消息 +- `$exception->getLine()` 错误行（当然这个没啥意义） + +[PHP 错误处理](http://php.net/manual/zh/book.errorfunc.php) +[PHP 异常类](http://php.net/manual/zh/class.exception.php) 当请求微信服务器失败或者返回错误时同样会触发此逻辑，错误代码请参考：http://mp.weixin.qq.com/wiki/17/fa4e1434e57290788bde25603fa2fcbd.html \ No newline at end of file