search

dodgepudding / wechat-php-sdk

微信公众平台php开发包, weixin developer SDK.
4.44k stars 2.33k forks source link

readme

wechat-php-sdk

微信公众平台php开发包,细化各项接口操作,支持链式调用,欢迎Fork此项目
weixin developer SDK. 项目地址：https://github.com/dodgepudding/wechat-php-sdk
项目blog：http://binsee.github.io/wechat-php-sdk

使用详解

使用前需先打开微信帐号的开发模式，详细步骤请查看微信公众平台接口使用说明：
微信公众平台： http://mp.weixin.qq.com/wiki/ 微信企业平台： http://qydev.weixin.qq.com/wiki/

微信支付接入文档： https://mp.weixin.qq.com/cgi-bin/readtemplate?t=business/course2_tmpl&lang=zh_CN

微信多客服：http://dkf.qq.com

目录

wechat.class.php 官方API类库
qywechat.class.php 企业号API类库
errCode.php|qyerrCode.php 全局返回码类
old_version/wechatpay.class.php 旧版微信支付V2接口类库
old_version/wechatext.class.php 非官方扩展API(停止维护)
old_version/wechatauth.class.php 授权登陆(停止维护)
old_version/wechat.js 内嵌JS(已废弃)
为开发框架进行适配
调用示例

1. wechat.class.php 官方API类库

调用官方API，具有更灵活的消息分类响应方式，支持链式调用操作 ；

主要功能

初始化动作

 $options = array(
    'token'=>'tokenaccesskey', //填写你设定的key
    'encodingaeskey'=>'encodingaeskey', //填写加密用的EncodingAESKey
    'appid'=>'wxdk1234567890', //填写高级调用功能的app id, 请在微信开发模式后台查询
    'appsecret'=>'xxxxxxxxxxxxxxxxxxx' //填写高级调用功能的密钥
    );
 $weObj = new Wechat($options); //创建实例对象
 //TODO：调用$weObj各实例方法

被动接口方法:

预定义常量列表：

////消息类型，使用实例调用getRevType()方法取得
const MSGTYPE_TEXT = 'text';
const MSGTYPE_IMAGE = 'image';
const MSGTYPE_LOCATION = 'location';
const MSGTYPE_LINK = 'link';
const MSGTYPE_EVENT = 'event';
const MSGTYPE_MUSIC = 'music';
const MSGTYPE_NEWS = 'news';
const MSGTYPE_VOICE = 'voice';
const MSGTYPE_VIDEO = 'video';
////事件类型，使用实例调用getRevEvent()方法取得
const EVENT_SUBSCRIBE = 'subscribe';       //订阅
const EVENT_UNSUBSCRIBE = 'unsubscribe';   //取消订阅
const EVENT_SCAN = 'SCAN';                 //扫描带参数二维码
const EVENT_LOCATION = 'LOCATION';         //上报地理位置
const EVENT_MENU_VIEW = 'VIEW';                     //菜单 - 点击菜单跳转链接
const EVENT_MENU_CLICK = 'CLICK';                   //菜单 - 点击菜单拉取消息
const EVENT_MENU_SCAN_PUSH = 'scancode_push';       //菜单 - 扫码推事件(客户端跳URL)
const EVENT_MENU_SCAN_WAITMSG = 'scancode_waitmsg'; //菜单 - 扫码推事件(客户端不跳URL)
const EVENT_MENU_PIC_SYS = 'pic_sysphoto';          //菜单 - 弹出系统拍照发图
const EVENT_MENU_PIC_PHOTO = 'pic_photo_or_album';  //菜单 - 弹出拍照或者相册发图
const EVENT_MENU_PIC_WEIXIN = 'pic_weixin';         //菜单 - 弹出微信相册发图器
const EVENT_MENU_LOCATION = 'location_select';      //菜单 - 弹出地理位置选择器
const EVENT_SEND_MASS = 'MASSSENDJOBFINISH';        //发送结果 - 高级群发完成
const EVENT_SEND_TEMPLATE = 'TEMPLATESENDJOBFINISH';//发送结果 - 模板消息发送结果
const EVENT_KF_SEESION_CREATE = 'kfcreatesession';  //多客服 - 接入会话
const EVENT_KF_SEESION_CLOSE = 'kfclosesession';    //多客服 - 关闭会话
const EVENT_KF_SEESION_SWITCH = 'kfswitchsession';  //多客服 - 转接会话
const EVENT_CARD_PASS = 'card_pass_check';          //卡券 - 审核通过
const EVENT_CARD_NOTPASS = 'card_not_pass_check';   //卡券 - 审核未通过
const EVENT_CARD_USER_GET = 'user_get_card';        //卡券 - 用户领取卡券
const EVENT_CARD_USER_DEL = 'user_del_card';        //卡券 - 用户删除卡券

主动接口方法:

2. wechatext.class.php 非官方扩展API

此扩展类库已经不再更新，原因是官方对公众号开放了众多接口，此类库继续维护的意义不大
非官方扩展API，需要配置公众平台账户和密码，能实现对已关注用户的点对点微信，此方式不保证长期有效。
类方法里提及的用户id在接口返回结构里表述为FakeId, 属同一概念, 在下面wechatauth类里则表示为Uin, 用户id对应的微信号必须通过getInfo()方法通过返回数组的Username值获取, 但非关注关系用户资料不能获取.
调用下列方法前必须经过login()方法和checkValid()验证方法才能获得调用权限. 有的账户无法通过登陆可能因为要求提供验证码, 可以手动登陆后把获取到的cookie写进程序存放cookie的文件解决.
程序使用了经过修改的snoopy兼容式HTTP类方法, 在类似BAE/SAE云服务器上可能不能正常运行, 因为云服务的curl方法是经过重写的, 某些header参数如网站来源参数不被支持.

类主要方法:

3. wechatauth.class.php 授权登陆

此扩展类库已经不再更新，原因是官方开放平台对网站应用开放的有授权登陆接口，更标准，更好用。请查看：微信开放平台
通过微信二维码登陆微信的API, 能实现第三方网站同步登陆, 首先程序分别通过get_login_code和get_code_image方法获取授权二维码图片, 然后利用微信手机客户端扫描二维码图片后将自动跳出授权页面, 用户点击授权后即可获取对应的用户资料和头像信息. 详细验证步骤请看test3.php例子.

类主要方法:

4. wechat.js 内嵌JS

此JS脚本已经废弃不再更新，原因是官方在微信6.0.2版本开放了全新的JSAPI接口，更全面好用。请查看：微信公众平台WIKI

微信内嵌网页特殊功能js调用：

5. errCode.php 全局返回码类

当调用API接口失败时，可以用此类来获取失败原因的中文说明。
注意：微信公众号引用errCode.php，企业号引用qyerrCode.php。

使用方法：

include "errCode.php";  //或 qyerrCode.php

$ret=ErrCode::getErrText(48001); //错误码可以通过公众号类库的公开变量errCode得到

if ($ret) 
    echo $ret;
else 
    echo "未找到对应的内容";

6. qywechat.class.php 企业号API类库

调用官方API，具有更灵活的消息分类响应方式，支持链式调用操作 ；

主要功能

初始化动作

$options = array(
  'token'=>'tokenaccesskey', //填写应用接口的Token
  'encodingaeskey'=>'encodingaeskey', //填写加密用的EncodingAESKey
  'appid'=>'wxdk1234567890', //填写高级调用功能的app id
  'appsecret'=>'xxxxxxxxxxxxxxxxxxx', //填写高级调用功能的密钥
  'agentid'=>'1', //应用的id
  'debug'=>false, //调试开关
  '_logcallback'=>'logg', //调试输出方法，需要有一个string类型的参数
);
 $weObj = new Wechat($options); //创建实例对象
 //TODO：调用$weObj各实例方法

被动接口方法:

预定义常量列表：

////消息类型，使用实例调用getRevType()方法取得
    const MSGTYPE_TEXT = 'text';
    const MSGTYPE_IMAGE = 'image';
    const MSGTYPE_LOCATION = 'location';
    const MSGTYPE_LINK = 'link';    //暂不支持
    const MSGTYPE_EVENT = 'event';
    const MSGTYPE_MUSIC = 'music';    //暂不支持
    const MSGTYPE_NEWS = 'news';
    const MSGTYPE_VOICE = 'voice';
    const MSGTYPE_VIDEO = 'video';
////事件类型，使用实例调用getRevEvent()方法取得
    const EVENT_SUBSCRIBE = 'subscribe';       //订阅
    const EVENT_UNSUBSCRIBE = 'unsubscribe';   //取消订阅
    const EVENT_LOCATION = 'LOCATION';         //上报地理位置
    const EVENT_ENTER_AGENT = 'enter_agent';   //用户进入应用
    const EVENT_MENU_VIEW = 'VIEW';                     //菜单 - 点击菜单跳转链接
    const EVENT_MENU_CLICK = 'CLICK';                   //菜单 - 点击菜单拉取消息
    const EVENT_MENU_SCAN_PUSH = 'scancode_push';       //菜单 - 扫码推事件(客户端跳URL)
    const EVENT_MENU_SCAN_WAITMSG = 'scancode_waitmsg'; //菜单 - 扫码推事件(客户端不跳URL)
    const EVENT_MENU_PIC_SYS = 'pic_sysphoto';          //菜单 - 弹出系统拍照发图
    const EVENT_MENU_PIC_PHOTO = 'pic_photo_or_album';  //菜单 - 弹出拍照或者相册发图
    const EVENT_MENU_PIC_WEIXIN = 'pic_weixin';         //菜单 - 弹出微信相册发图器
    const EVENT_MENU_LOCATION = 'location_select';      //菜单 - 弹出地理位置选择器
    const EVENT_SEND_MASS = 'MASSSENDJOBFINISH';        //发送结果 - 高级群发完成
    const EVENT_SEND_TEMPLATE = 'TEMPLATESENDJOBFINISH';//发送结果 - 模板消息发送结果

主动接口方法：

7. wechatpay.class.php 旧版微信支付V2接口类库

旧版微信支付类库(微信支付V2)，已移动至old_version目录下。
自2014年8月开始申请到的微信支付都是V3接口，据官方说V2的会陆续升级为V3接口，但时间及升级渠道未确认。

主要功能

初始化动作

 $options = array(
    'appid'=>'wxdk1234567890', //填写高级调用功能的app id, 请在微信开发模式后台查询
    'appsecret'=>'xxxxxxxxxxxxxxxxxxx', //填写高级调用功能的密钥
    'partnerid'=>'88888888', //财付通商户身份标识，支付权限专用，没有可不填
    'partnerkey'=>'', //财付通商户权限密钥Key，支付权限专用
    'paysignkey'=>'' //商户签名密钥Key，支付权限专用
    );
 $weObj = new Wechat($options); //创建实例对象
 //TODO：调用$weObj各实例方法

主动接口方法:

为开发框架进行适配

为不同的开发框架进行适配缓存操作(保存access_token、jsapi_ticket)，及输出调试日志。

由于微信api需要缓存access_token与jsapi_ticket，而在不同框架下的缓存方式不同，所以原先在Wechat.class.php和QYWechat.class.php中缓存代码做了TODO标志。 需要各位在使用不同框架时再进行修改，但确实很麻烦，因为对结构进行了修改。

取消了原先同步维护的Thinkphp版本，为Wechat类增加操作缓存3个重载方法setCache, getCache, removeCache，以及修改log方法可以重载。 分别来实现在不同开发框架下的设置缓存、读取缓存、清除缓存、日志输出4个功能。

在不同的开发框架下使用Wechat类库，请继承Wechat类，根据需要实现这4个方法。
可参考Thinkphp版的TPWechat.class.php为不同框架进行适配。 欢迎提交其他框架的适配文件到项目库来。

为Thinkphp进行适配的示例如下：

/**
 *  微信公众平台PHP-SDK, ThinkPHP实例
 *  @author dodgepudding@gmail.com
 *  @link https://github.com/dodgepudding/wechat-php-sdk
 *  @version 1.2
 *  usage:
 *   $options = array(
 *          'token'=>'tokenaccesskey', //填写你设定的key
 *          'encodingaeskey'=>'encodingaeskey', //填写加密用的EncodingAESKey
 *          'appid'=>'wxdk1234567890', //填写高级调用功能的app id
 *          'appsecret'=>'xxxxxxxxxxxxxxxxxxx' //填写高级调用功能的密钥
 *      );
 *   $weObj = new TPWechat($options);
 *   $weObj->valid();
 *   ...
 *  
 */
class TPWechat extends Wechat
{
    /**
     * log overwrite
     * @see Wechat::log()
     */
    protected function log($log){
        if ($this->debug) {
            if (function_exists($this->logcallback)) {
                if (is_array($log)) $log = print_r($log,true);
                return call_user_func($this->logcallback,$log);
            }elseif (class_exists('Log')) {
                Log::write('wechat：'.$log, Log::DEBUG);
            }
        }
        return false;
    }

    /**
     * 重载设置缓存
     * @param string $cachename
     * @param mixed $value
     * @param int $expired
     * @return boolean
     */
    protected function setCache($cachename,$value,$expired){
        return S($cachename,$value,$expired);
    }

    /**
     * 重载获取缓存
     * @param string $cachename
     * @return mixed
     */
    protected function getCache($cachename){
        return S($cachename);
    }

    /**
     * 重载清除缓存
     * @param string $cachename
     * @return boolean
     */
    protected function removeCache($cachename){
        return S($cachename,null);
    }
}

调用示例

官方Wechat调用示例：

//test1.php
include "wechat.class.php";
$options = array(
        'token'=>'tokenaccesskey', //填写你设定的key
        'encodingaeskey'=>'encodingaeskey' //填写加密用的EncodingAESKey，如接口为明文模式可忽略
    );
$weObj = new Wechat($options);
$weObj->valid();//明文或兼容模式可以在接口验证通过后注释此句，但加密模式一定不能注释，否则会验证失败
$type = $weObj->getRev()->getRevType();
switch($type) {
    case Wechat::MSGTYPE_TEXT:
            $weObj->text("hello, I'm wechat")->reply();
            exit;
            break;
    case Wechat::MSGTYPE_EVENT:
            break;
    case Wechat::MSGTYPE_IMAGE:
            break;
    default:
            $weObj->text("help info")->reply();
}

企业号API类库调用示例：

可参考test目录下的qydemo.php

include "wechat.class.php";
$options = array(
        'token'=>'9Ixxxxxxx',   //填写应用接口的Token
        'encodingaeskey'=>'d4o9WVg8sxxxxxxxxxxxxxxxxxxxxxx',//填写加密用的EncodingAESKey
        'appid'=>'wxa07979baxxxxxxxx',  //填写高级调用功能的appid
);
$weObj = new Wechat($options);
$weObj->valid(); //注意, 企业号与普通公众号不同，必须打开验证，不要注释掉
$type = $weObj->getRev()->getRevType();
switch($type) {
    case Wechat::MSGTYPE_TEXT:
            $weObj->text("hello, I'm wechat")->reply();
            exit;
            break;
    case Wechat::MSGTYPE_EVENT:
            break;
    case Wechat::MSGTYPE_IMAGE:
            break;
    default:
            $weObj->text("help info")->reply();
}

扩展包Wechatext调用示例:

// old_version/test/test2.php 
    include "wechatext.class.php";

    function logdebug($text){
        file_put_contents('./data/log.txt',$text."\n",FILE_APPEND);     
    };

    $options = array(
        'account'=>'demo@domain.com',
        'password'=>'demo',
        'datapath'=>'./data/cookie_',
            'debug'=>true,
            'logcallback'=>'logdebug'   
    ); 
    $wechat = new Wechatext($options);
    if ($wechat->checkValid()) {
        // 获取用户信息
        $data = $wechat->getInfo('3974255');
        var_dump($data);
        // 获取最新一条消息
        $topmsg = $wechat->getTopMsg();
        var_dump($topmsg);
        // 主动回复消息
        if ($topmsg && $topmsg['has_reply']==0)
        $wechat->send($topmsg['fakeid'],'hi '.$topmsg['nick_name'].',rev:'.$topmsg['content']); 
    }

微信二维码Wechatauth登陆示例:

// old_version/test/test3.php
    include "../wechatauth.class.php";
    session_start();
    $sid  = session_id();
    $options = array(
        'account'=>$sid,
        'datapath'=>'../data/cookiecode_',
    ); 
    $wechat = new Wechatauth($options);

    if (isset($_POST['code'])) {
        $logincode = $_POST['code'];
        $vres = $wechat->set_login_code($logincode)->verify_code();
        if ($vres===false) {
            $result = array('status'=>0);
        } else {
            $result = array('status'=>$vres);
            if ($vres==200) {
                $result['info'] = $wechat->get_login_info();
                $result['cookie'] = $wechat->get_login_cookie(true);
            }
        }

        die(json_encode($result));  
    }
    $logincode =  $wechat->get_login_code(); //获取授权码
    $qrimg = $wechat->get_code_image(); //待输出的二维码图片

HTML部分请看old_version/test/test3.php, 主要是定时ajax查询是否已经授权成功

新版微信JSAPI调用DEMO:

请看test/jsapi目录

License

This is licensed under the GNU LGPL, version 2.1 or later.
For details, see: http://creativecommons.org/licenses/LGPL/2.1/