From df455027424cbf317eeb05ee9562c7bc5ae4e6ad Mon Sep 17 00:00:00 2001 From: overtrue Date: Wed, 11 Feb 2015 00:31:29 +0800 Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0wiki?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- 多客服的消息转发.md | 23 +++++++++++++++++++ 安装.md | 22 ++++++++++++++++++ 客服管理与发送消息.md | 23 +++++++++++++++++++ 接收消息与回复.md | 35 ++++++++++++++++++++++++++++ 消息的使用.md | 53 +++++++++++++++++++++++++++++++++++++++++++ 用户与用户组管理.md | 28 +++++++++++++++++++++++ 监听微信事件.md | 37 ++++++++++++++++++++++++++++++ 签名计算.md | 18 +++++++++++++++ 网页授权.md | 24 ++++++++++++++++++++ 自定义缓存.md | 17 ++++++++++++++ 自定义菜单.md | 9 ++++++++ 获取JSSDK的Ticket.md | 6 +++++ 配置与初始化.md | 26 +++++++++++++++++++++ 错误处理.md | 15 ++++++++++++ 14 files changed, 336 insertions(+) create mode 100644 多客服的消息转发.md create mode 100644 安装.md create mode 100644 客服管理与发送消息.md create mode 100644 接收消息与回复.md create mode 100644 消息的使用.md create mode 100644 用户与用户组管理.md create mode 100644 监听微信事件.md create mode 100644 签名计算.md create mode 100644 网页授权.md create mode 100644 自定义缓存.md create mode 100644 自定义菜单.md create mode 100644 获取JSSDK的Ticket.md create mode 100644 配置与初始化.md create mode 100644 错误处理.md diff --git a/多客服的消息转发.md b/多客服的消息转发.md new file mode 100644 index 0000000..3baba0a --- /dev/null +++ b/多客服的消息转发.md @@ -0,0 +1,23 @@ +多客服的消息转发绝对是超级的简单： + + ```php + + use Overtrue\Wechat\Services\Message; + + // 转发收到的消息给客服 + $wechat->on('message', function($message) { + return Message::make('transfer'); + }); + + $result = $wechat->serve(); + + echo $result; + ``` + +当然，你也可以指定转发给某一个客服： + +```php +return Message::make('transfer')->account($account); +// 或者 +return Message::make('transfer')->to($account); +``` \ No newline at end of file diff --git a/安装.md b/安装.md new file mode 100644 index 0000000..4bc6c38 --- /dev/null +++ b/安装.md @@ -0,0 +1,22 @@ +环境要求: PHP >= 5.3.0 + +1. 使用composer: + + ```shell + composer require overtrue/wechat + ``` + +2. 手动安装 + + 下载[最新版zip包](https://github.com/overtrue/wechat/archive/master.zip) 或者下载指定版本:https://github.com/overtrue/wechat/releases + + 然后引入根目录的autoload.php即可： + + ```php + staff; + ``` + ++ `$staff->all();` 获取所有客服账号 ++ `$staff->allOnline();` 获取所有在线的客服账号 ++ `$staff->create($mail, $nickname, $password);` 添加客服帐号 ++ `$staff->update($mail, $nickname, $password);` 修改客服帐号 ++ `$staff->delete($mail, $nickname, $password);` 删除客服帐号 ++ `$staff->avatar($mail, $avatarPath);` 设置客服帐号的头像 ++ `$staff->send($message)->to($openId);` 主动发送消息给用户 ++ 群发消息 + + ```php + // 所有人 + $staff->send($message)->toAll(); + // 指定组 + $staff->send($message)->toGroup($groupId); + // 多个人 + $staff->send($message)->toThem(array($openId, $openId, ...)); + ``` diff --git a/接收消息与回复.md b/接收消息与回复.md new file mode 100644 index 0000000..79dba03 --- /dev/null +++ b/接收消息与回复.md @@ -0,0 +1,35 @@ +消息的监听再简单不过了，你不需要像其它SDK一样麻烦，这将会是前所未有的简单，你可以选择监听所有类型或者指定某种类型，以及作出相应的响应，比如回复一条应答消息。 + +```php +$wechat->on('message', callable $callback); // 全部类型 +// or +$wechat->on('message', string $messageType, callable $callback); // 只监听指定类型 +``` + +参数说明 + +- `$messageType` string, 指定要处理的消息类型，ex：`image` +- `$callback` callable, 回调函数，closure匿名函数，或者一切可调用的方法或者函数 + +example: + +```php + +use Overtrue\Wechat\Services\Message; + +// 监听所有类型 +$wechat->on('message', function($message) { + return Message::make('text')->content('您好！'); +}); + +// 监听指定类型 +$wechat->on('message', 'image', function($message) { + return Message::make('text')->content('我们已经收到您发送的图片！'); +}); + +$result = $wechat->serve(); + +echo $result; +``` + +关于更多消息内容请参考： \ No newline at end of file diff --git a/消息的使用.md b/消息的使用.md new file mode 100644 index 0000000..ce4b6a2 --- /dev/null +++ b/消息的使用.md @@ -0,0 +1,53 @@ +我把微信的API里的所有“消息”都按类型抽象出来了，也就是说，你不用区分它是回复消息还是主动推送消息，免去了你去手动拼装微信那帮SB那么恶心的XML以及乱七八糟命名不统一的JSON了，我帮忙你承受这份苦。 + +### 消息的类型及属性 + +| 消息类型 | 类型名称 | 属性 | 除属性自身外提供的方法 | +|----------|----------|----------------------------------------------------------------------------------|-------------------------------------------| +| 文本 | `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)` | +| 位置 | `location` | `lat` 地理位置纬度
`lon` 地理位置经度
`scale` 地图缩放大小
`label` 地理位置信息 | | +| 链接 | `link` | `title` 标题
`description` 描述
url 链接URL | | + +### 创建消息 + +**请注意：消息类的命名空间为 `Overtrue\Wechat\Services\Message`** + +```php +on('event', 'subscribe', function($event){ + return Message::make('text')->content('您好！欢迎关注overtrue'); +}); +``` + +这里有一点需要注意，当属性带下划线的时候，方法名是支持两种的：`media_id()` 或者 `mediaId()` 都一样。 + +### 上传媒体文件 + + +```php +$message = Message::make('image')->media('D:/test/demo.jpg'); +``` + +媒体文件你不用上传，也就是说media_id是我来维护，你直接传本地文件就好了。 +方法`media($file)`会上传文件然后赋值到`media_id`属性。如果想要获取上传后的media_id: + +```php +$mediaId = $message->media_id; +``` + +#### 这里有两个方法用于设置媒体文件： + +- `media($file)` 对应设置 `media_id` +- `thumb($file)` 对应设置 `thumb_media_id` \ No newline at end of file diff --git a/用户与用户组管理.md b/用户与用户组管理.md new file mode 100644 index 0000000..068fb5a --- /dev/null +++ b/用户与用户组管理.md @@ -0,0 +1,28 @@ +## 用户 + + ```php + $userService = $wechat->user; + ``` + ++ `$userService->get($openId);` 获取用户信息 ++ `$userService->all($nextOpenId = null);` 获取用户列表, $nextOpenId 可选 ++ `$userService->remark($openId, $remark);` 修改用户备注, 返回boolean + +example: + +```php +$user = $userService->get($openId); + +echo $user->nickname; +``` + +## 用户组 + + ```php + $group = $wechat->group; + ``` + ++ `$group->all();` 获取所有分组 ++ `$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 new file mode 100644 index 0000000..8ad9eb0 --- /dev/null +++ b/监听微信事件.md @@ -0,0 +1,37 @@ +所有的事件都可以很方便的监听与处理，与监听消息一样，同样支持监听全部类型或者指定类型。 +关于事件类型请参考微信官方文档：http://mp.weixin.qq.com/wiki/2/5baf56ce4947d35003b86a9805634b1e.html + +```php +$wechat->on('event', callable $callback); +// or +$wechat->on('event', string $eventType, callable $callback); +``` + +参数说明 + +- `$eventType` string, 指定要处理的消息类型，ex：`image` +- `$callback` callable, 回调函数，closure匿名函数，或者一切可调用的方法或者函数 + +example: + +```php + +use Overtrue\Wechat\Services\Message; + +// 监听所有事件 +$wechat->on('event', function($event) { + error_log('收到取消关注事件，取消关注者openid: ' . $event['FromUserName']); +}); + +// 只监听指定类型事件 +$wechat->on('event', 'subscribe', function($event) { + + error_log('收到关注事件，关注者openid: ' . $event['FromUserName']); + + return Message::make('text')->content('感谢您关注'); +}); + +$result = $wechat->serve(); + +echo $result; +``` diff --git a/签名计算.md b/签名计算.md new file mode 100644 index 0000000..8500e5a --- /dev/null +++ b/签名计算.md @@ -0,0 +1,18 @@ +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..53a4bc5 --- /dev/null +++ b/网页授权.md @@ -0,0 +1,24 @@ + ```php + $wechat->auth; + ``` + ++ 生成授权链接 + + ```php + // 生成并返回 + $wechat->auth->url($to, $state, $scope); + // 直接跳转 + $wechat->auth->redirect($to, $state, $scope); 直接跳转 + ``` + ++ 判断是否已经授权 + + ```php + $wechat->auth->authorized(); + ``` + ++ 获取授权用户 + + ```php + $wechat->auth->user(); + ``` \ No newline at end of file diff --git a/自定义缓存.md b/自定义缓存.md new file mode 100644 index 0000000..0179d2f --- /dev/null +++ b/自定义缓存.md @@ -0,0 +1,17 @@ +微信的access_token是不能太频繁的调用的，所以需要缓存，本SDK默认使用文件缓存，文件会创建在代码运行环境的临时目录里，使用[sys_get_temp_dir()](http://php.net/manual/zh/function.sys-get-temp-dir.php) 函数获取的临时目录下。 + +如果你需要自定义缓存方式，那么Wechat提供了以下两个方法： + +```php +// 写入 +$wechat->cache->setter(function($key, $value, $lifetime){ + return your_custom_set_cache($key, $value, $lifetime); +}); + +// 读取 +$wechat->cache->getter(function($key){ + return your_custom_get_cache($key); +}); +``` + +当你的`getter` 没有返回缓存的值时，会重新请求access_token。 \ No newline at end of file diff --git a/自定义菜单.md b/自定义菜单.md new file mode 100644 index 0000000..8c02fb2 --- /dev/null +++ b/自定义菜单.md @@ -0,0 +1,9 @@ + ```php + $wechat->menu; + ``` + ++ `$menu->get();` 读取菜单 ++ `$menu->set($menus);` 设置菜单 ++ `$menu->delete();` 删除菜单 + +> 待补充... \ No newline at end of file diff --git a/获取JSSDK的Ticket.md b/获取JSSDK的Ticket.md new file mode 100644 index 0000000..955cabb --- /dev/null +++ b/获取JSSDK的Ticket.md @@ -0,0 +1,6 @@ +```php +$wechat->ticket->js(); +$wechat->ticket->card(); +``` + +> 待补充 \ No newline at end of file diff --git a/配置与初始化.md b/配置与初始化.md new file mode 100644 index 0000000..b6e63bc --- /dev/null +++ b/配置与初始化.md @@ -0,0 +1,26 @@ +本项目的用法目前网上其它SDK用法不同，这里只需要像下面这样配置一次完成： + +```php + 'Your app id', + 'secret' => 'Your secret' + 'token' => 'Your token', + 'encodingAESKey' => 'Your encoding AES Key' // optional +]; + +$wechat = Wechat::make($options); + +$server = $wechat->on('message', function($message){ + error_log("收到来自'{$message['FromUserName']}'的消息：" . $message['Content']); +}); + +$result = $wechat->serve(); + +// 您可以直接echo 或者返回给框架 +echo $result; +``` +`$wechat->serve()` 方法返回的值为字符串或者空，用于应答微信服务器的推送，消息或者事件等。比如你如果使用的是Laravel,你这里就应该 `return $wechat->serve();` \ No newline at end of file diff --git a/错误处理.md b/错误处理.md new file mode 100644 index 0000000..d7c84ef --- /dev/null +++ b/错误处理.md @@ -0,0 +1,15 @@ +所有的错误均使用异常抛出 + +```php + $wechat->error(function($error){ + error_log("code:" . $error->getCode . ' error: ' . $error->getMessage()); + }); +``` + +这里的回调函数的第一个参数为继承自Exception的异常类，所以你可以使用Exception的所有方法。 + +- `$error->getCode()` 错误码，ex: `40001` +- `$error->getMessage()` 错误消息 +- `$error->getLine()` 错误行（当然这个没啥意义） + +当请求微信服务器失败或者返回错误时同样会触发此逻辑，错误代码请参考：http://mp.weixin.qq.com/wiki/17/fa4e1434e57290788bde25603fa2fcbd.html \ No newline at end of file