EasyWeChat、微信公众平台实现带参数二维码、微信事件处理以及微信详细用户信息获取

一、生成带参数的二维码

为了满足用户渠道推广分析和用户帐号绑定等场景的需要，公众平台提供了生成带参数二维码的接口。使用该接口可以获得多个带不同场景值的二维码，用户扫描后，公众号可以接收到事件推送。

目前有2种类型的二维码：

1、临时二维码，是有过期时间的，最长可以设置为在二维码生成后的30天（即2592000秒）后过期，但能够生成较多数量。临时二维码主要用于帐号绑定等不要求二维码永久保存的业务场景
2、永久二维码，是无过期时间的，但数量较少（目前为最多10万个）。永久二维码主要用于适用于帐号绑定、用户来源统计等场景。

用户扫描带场景值二维码时，可能推送以下两种事件：

如果用户还未关注公众号，则用户可以关注公众号，关注后微信会将带场景值关注事件推送给开发者。

如果用户已经关注公众号，在用户扫描后会自动进入会话，微信也会将带场景值扫描事件推送给开发者。

获取带参数的二维码的过程包括两步，首先创建二维码ticket，然后凭借ticket到指定URL换取二维码。

创建二维码ticket

每次创建二维码ticket需要提供一个开发者自行设定的参数（scene_id），分别介绍临时二维码和永久二维码的创建二维码ticket过程。

临时二维码请求说明

http请求方式: POST
URL: https://api.weixin.qq.com/cgi-bin/qrcode/create?access_token=TOKENPOST数据格式：json
POST数据例子：{"expire_seconds": 604800, "action_name": "QR_SCENE", "action_info": {"scene": {"scene_id": 123}}}

或者也可以使用以下POST数据创建字符串形式的二维码参数：
{"expire_seconds": 604800, "action_name": "QR_STR_SCENE", "action_info": {"scene": {"scene_str": "test"}}}

永久二维码请求说明

http请求方式: POST
URL: https://api.weixin.qq.com/cgi-bin/qrcode/create?access_token=TOKENPOST数据格式：json
POST数据例子：{"action_name": "QR_LIMIT_SCENE", "action_info": {"scene": {"scene_id": 123}}}

或者也可以使用以下POST数据创建字符串形式的二维码参数：
{"action_name": "QR_LIMIT_STR_SCENE", "action_info": {"scene": {"scene_str": "test"}}}

参数说明

参数	说明
expire_seconds	该二维码有效时间，以秒为单位。 最大不超过2592000（即30天），此字段如果不填，则默认有效期为30秒。
action_name	二维码类型，QR_SCENE为临时的整型参数值，QR_STR_SCENE为临时的字符串参数值，QR_LIMIT_SCENE为永久的整型参数值，QR_LIMIT_STR_SCENE为永久的字符串参数值
action_info	二维码详细信息
scene_id	场景值ID，临时二维码时为32位非0整型，永久二维码时最大值为100000（目前参数只支持1--100000）
scene_str	场景值ID（字符串形式的ID），字符串类型，长度限制为1到64

返回说明

正确的Json返回结果:

{"ticket":"gQH47joAAAAAAAAAASxodHRwOi8vd2VpeGluLnFxLmNvbS9xL2taZ2Z3TVRtNzJXV1Brb3ZhYmJJAAIEZ23sUwMEmm

3sUw==","expire_seconds":60,"url":"http:\/\/weixin.qq.com\/q\/kZgfwMTm72WWPkovabbI"}

参数	说明
ticket	获取的二维码ticket，凭借此ticket可以在有效时间内换取二维码。
expire_seconds	该二维码有效时间，以秒为单位。 最大不超过2592000（即30天）。
url	二维码图片解析后的地址，开发者可根据该地址自行生成需要的二维码图片

通过ticket换取二维码

获取二维码ticket后，开发者可用ticket换取二维码图片。请注意，本接口无须登录态即可调用。

请求说明

HTTP GET请求（请使用https协议）https://mp.weixin.qq.com/cgi-bin/showqrcode?ticket=TICKET提醒：TICKET记得进行UrlEncode

返回说明

ticket正确情况下，http 返回码是200，是一张图片，可以直接展示或者下载。

HTTP头（示例）如下：
Accept-Ranges:bytes
Cache-control:max-age=604800
Connection:keep-alive
Content-Length:28026
Content-Type:image/jpg
Date:Wed, 16 Oct 2013 06:37:10 GMT
Expires:Wed, 23 Oct 2013 14:37:10 +0800
Server:nginx/1.4.1

错误情况下（如ticket非法）返回HTTP错误码404

二、获取微信用户详细信息

用户信息的获取是微信开发中比较常用的一个功能了，以下所有的用户信息的获取与更新，都是基于微信的 openid的，并且是已关注当前账号的，其它情况可能无法正常使用。

获取实例

<?php use EasyWeChat\ Foundation\ Application; // ... $app = new Application($options); $userService = $app->user;

API 列表

获取用户信息

$userService->get($openId); $userService->batchGet($openIds);

获取单个：

$user = $userService->get($openId); echo $user->nickname; // or $user['nickname']

获取多个：

$users = $userService->batchGet([$openId1, $openId2, ...]);

获取用户列表

$userService->lists($nextOpenId = null); // $nextOpenId 可选

example:

$users = $userService->lists(); // result { "total": 2, "count": 2, "data": { "openid": [ "", "OPENID1", "OPENID2" ] }, "next_openid": "NEXT_OPENID" } $users->total; // 2

修改用户备注

$userService->remark($openId, $remark); // 成功返回boolean

example:

$userService->remark($openId, "僵尸粉");

获取用户所属用户组ID

$userService->group($openId);

example:

$userGroupId = $userService->group($openId);

获取公众号的黑名单列表

$userService->blacklist($beginOpenId = null);

example:

$blacklist = $userService->blacklist();

拉黑用户

$userService->batchBlock( array $openidList);

example:

$userService->batchBlock([ 'openid1', 'openid2', 'openid3', '...']);

取消拉黑用户

$userService->batchUnblock( array $openidList);

example:

$userService->batchUnblock([ 'openid1', 'openid2', 'openid3', '...']);

其它

三、微信事件处理

我们在入门小教程一节以服务端为例讲解了一个基本的消息的处理，这里就不再讲服务器验证的流程了，请直接参考前面的入门实例即可。

服务端的作用呢，在整个微信开发中主要是负责 接收用户发送过来的消息，还有 用户触发的一系列事件。

首先我们得厘清一下消息与事件的回复，当你收到用户消息后（消息由微信服务器推送到你的服务器），在你对消息进行一些处理后，不管是选择回复一个消息还是什么不都回给用户，你也应该给微信服务器一个 “答复”，如果是选择回复一条消息，就直接返回一个消息xml就好，如果选择不作任何回复，你也得回复一个空字符串或者字符串 SUCCESS（不然用户就会看到 该公众号暂时无法提供服务）。

基本使用

在 SDK 中呢，使用 setMessageHandler(callable $callback) 来设置消息处理函数：

<?php use EasyWeChat\ Foundation\ Application; // ... $app = new Application($options); // 从项目实例中得到服务端应用实例。 $server = $app->server; $server->setMessageHandler( function ($message) { // $message->FromUserName // 用户的 openid // $message->MsgType // 消息类型：event, text.... return "您好！欢迎关注我!"; }); $response = $server->serve(); $response->send(); // Laravel 里请使用：return $response;

这里我们使用 setMessageHandler 传入了一个 闭包（Closure），该闭包接收一个参数 $message 为消息对象（Collection），这里需要注意的时，与 2.0 不同，2.0 当中我们对消息与事件做了区分，还对消息进行了分类（按 MsgType）。在 3.0 后，所有的消息包括事件都会使用 setMessageHandler 来处理，也就是说你可能需要在里面进行一些判断，例如：

$server->setMessageHandler( function ($message) { switch ($message->MsgType) { case 'event': return '收到事件消息'; break; case 'text': return '收到文字消息'; break; case 'image': return '收到图片消息'; break; case 'voice': return '收到语音消息'; break; case 'video': return '收到视频消息'; break; case 'location': return '收到坐标消息'; break; case 'link': return '收到链接消息'; break; // ... 其它消息 default: return '收到其它消息'; break; } // ... });

当然，因为这里 setMessageHandler 接收一个 callable 的参数，所以你不一定要传入一个 Closure 闭包，你可以选择传入一个函数名，一个 [$class, $method] 或者 Foo::bar 这样的类型。

 注意，默认没有验证是否为微信的请求，部署上线建议关掉 debug 模式。

某些情况，我们需要直接使用 $message 参数，那么怎么在 setMessageHandler 闭包外调用呢？

$message = $server->getMessage();

注意：$message 是一个数组类型的数据，使用的时候这样使用：$message['ToUserName']

请求消息的属性

当你接收到用户发来的消息时，可能会提取消息中的相关属性，那么请参考：

请求消息基本属性(以下所有消息都有的基本属性)：

$message->ToUserName    接收方帐号（该公众号 ID）
$message->FromUserName  发送方帐号（OpenID, 代表用户的唯一标识）
$message->CreateTime    消息创建时间（时间戳）
$message->MsgId         消息 ID（64位整型）

文本：

$message->MsgType  text
$message->Content  文本消息内容

图片：

$message->MsgType  image
$message->PicUrl   图片链接

语音：

$message->MsgType        voice
$message->MediaId        语音消息媒体id，可以调用多媒体文件下载接口拉取数据。
$message->Format         语音格式，如 amr，speex 等
$message->Recognition * 开通语音识别后才有

> 请注意，开通语音识别后，用户每次发送语音给公众号时，微信会在推送的语音消息XML数据包中，增加一个 `Recongnition` 字段

视频：

$message->MsgType       video
$message->MediaId       视频消息媒体id，可以调用多媒体文件下载接口拉取数据。
$message->ThumbMediaId  视频消息缩略图的媒体id，可以调用多媒体文件下载接口拉取数据。

小视频：

$message->MsgType     shortvideo
$message->MediaId     视频消息媒体id，可以调用多媒体文件下载接口拉取数据。
$message->ThumbMediaId    视频消息缩略图的媒体id，可以调用多媒体文件下载接口拉取数据。

事件：

$message->MsgType     event
$message->Event       事件类型 （如：subscribe(订阅)、unsubscribe(取消订阅) ...， CLICK 等）

# 扫描带参数二维码事件
$message->EventKey    事件KEY值，比如：qrscene_123123，qrscene_为前缀，后面为二维码的参数值
$message->Ticket      二维码的 ticket，可用来换取二维码图片

# 上报地理位置事件
$message->Latitude    23.137466   地理位置纬度
$message->Longitude   113.352425  地理位置经度
$message->Precision   119.385040  地理位置精度

# 自定义菜单事件
$message->EventKey    事件KEY值，与自定义菜单接口中KEY值对应，如：CUSTOM_KEY_001, www.qq.com

地理位置：

$message->MsgType     location
$message->Location_X  地理位置纬度
$message->Location_Y  地理位置经度
$message->Scale       地图缩放大小
$message->Label       地理位置信息

链接：

$message->MsgType      link
$message->Title        消息标题
$message->Description  消息描述
$message->Url          消息链接

回复消息

回复的消息可以为 null，此时 SDK 会返回给微信一个 “SUCCESS”，你也可以回复一个普通字符串，比如：欢迎关注 overtrue.，此时 SDK 会对它进行一个封装，产生一个 EasyWeChat\Message\Text 类型的消息并在最后的 $server->serve(); 时生成对应的消息 XML 格式。

如果你想返回一个自己手动拼的原生 XML 格式消息，请返回一个 EasyWeChat\Message\Raw 实例即可。