WeChatPHP-SDK

SDK to admin.wechat.com for php

TODO

API update: 高级群发接口 Request:

• Update WeChatServer.php
• Update WeChatClient.php
• Update Test
• Update Documents

Logs

• 2014-04-16 json_encode unicode escape fix
• 2014-03-27 Fix WeChatServer Response media
• 2014-02-18 add bnner & zh_CN setting for WeChatClient
• 2014-01-23 Upload

links

• WeChatPHP-SDK@github
• WeChat OA Developer Wiki
• 微信公众平台开发者文档
• Zem's Blog

###WeChatServer.php

About

WeChatServer is used to start an api for admin.wechat.com to connect.

Getting start with Hook

Hook mark the position in process and you can handle data/process there.

Wiki

• Common Messages
• Event Messages

Hook List

# ============================================================
# Hook  Name                || Handle Function
# ============================================================
# All the event name you can use.
# 
# ============================================================
# receiveAllStart           => function( $postObj ){ ... }
# receiveMsg::text          => /\
# receiveMsg::location      => ||
# receiveMsg::image         => ||
# receiveMsg::video         => ||
# receiveMsg::link          => /\
# receiveMsg::voice         => ||
# receiveEvent::subscribe   => ||
# receiveEvent::unsubscribe => ||
# receiveEvent::scan        => ||
# receiveEvent::location    => /\
# receiveEvent::click       => ||
# receiveAllEnd             => ||
# accessCheckSuccess        => ||
# 404                       => /\
# ============================================================

How to use hook?

<?PHP 
  include('WeChatServer.php');
  function handle( $postData ){
    // your code here...
  }
  $svr = new WeChatServer( 
    'your-token', 
    array( /* Hook here */
        'HookName' => 'Handle Function Name OR Function'
        /* demo */
        'receiveMsg::text'     => 'handle',
        'receiveMsg::location' => handle,
        'receiveMsg::image'    => function( $postData ){ /* your code here */ }
      ) 
  );

Hooks detail:

• receiveAllStart [1st Hook before all]

  $postData = array( 
    # Base Keys:
    'id'   => /* message id          */ ,
    'from' => /* follower open id    */ ,
    'to'   => /* admin OA account id */ ,
    'time' => /* msg timestamp       */ ,
    'type' => /* message type        */
  ) + receiveMsg OR receiveEvent

• receiveMsg::text [type = text]

  $postData = array( 
    /* ... base ... */ 
    'content' => /* text content */
  )

• receiveMsg::location [type = location]

$postData = array( 
    /* ... base ... */
    'X' => /* latitude   */ ,
    'Y' => /* longitude  */ ,
    'S' => /* scale      */ ,
    'I' => /* label info */
  )

• receiveMsg::image [type = image]

$postData = array(
    /* ... base ... */
    'url' => /* image url                                      */ ,
    'mid' => /* image media id (can download or sent to other) */
  )

• receiveMsg::video [type = video]

$postData = array(
    /* ... base ... */
    'mid       => /* video media id       */ ,
    'thumbmid' => /* thumb image media id */
  )

• receiveMsg::link [type = link]

$postData = array(
    /* ... base ... */
    'title' => /* title       */ ,
    'desc'  => /* description */ ,
    'url'   => /* link url    */
  )

• receiveMsg::voice [type = voice]

$postData = array(
    /* ... base ... */
    'mid'     => /* voice media id                        */ ,
    'format'  => /* voice format for exp : amr, speex ... */
    [ , 'txt' => /* voice recognition result              */ ]
  )

• receiveEvent::subscribe [type = event & event = subscribe]

$postData = array(
    /* ... base ... */
    'event'      => /* event name          */ ,
    [ , 'key'    => /* qrcode option value */
      , 'ticket' => /* qrcode ticket       */
    ]
  )

• receiveEvent::unsubscribe [type = event & event = unsubscribe]

$postData = array(
    /* ... base ... */
    'event'      => /* event name */
  )

• receiveEvent::scan [type = event & event = scan]

$postData = array(
    /* ... base ... */
    'event'      => /* event name          */ ,
    [ , 'key'    => /* qrcode option value */
      , 'ticket' => /* qrcode ticket       */
    ]
  )

• receiveEvent::location [type = event & event = location]

$postData = array(
    /* ... base ... */
    'event' => /* event name */ ,
    'la'    => /* Latitude   */ ,
    'lo'    => /* Longitude  */ ,
    'p'     => /* Precision  */
)

• receiveEvent::click [type = event & event = click]

$postData = array(
    /* ... base ...*/
    'event' => /* event name */ ,
    'key'   => /* custom key */
)

• receiveAllEnd [Last Hook]

$postData = array(
    'id'   => /* message id          */ ,
    'from' => /* follower open id    */ ,
    'to'   => /* admin OA account id */ ,
    'time' => /* msg timestamp       */ ,
    'type' => /* message type        */
) + receiveMsg OR receiveEvent

• accessCheckSuccess (without params)
• 404 (without params)

#####get xml In hook you can send response by use

echo WeChatServer::getXml4* # ...

Callback Message

• Text

    {String} WeChatServer::getXml4Txt( $text );
  

• Image

    {String} WeChatServer::getXml4ImgByMid( $mediaid );
  

• Voice

    {String} WeChatServer::getXml4VoiceByMid( $mediaid );
  

• Video

    {String} WeChatServer::getXml4VideoByMid( 
                $mediaid, $title 
                [, $description=$title as Default ] 
             );
  

• Music

    {String} WeChatServer::getXml4MusicByUrl( 
                 $music_url, $mediaid_thumb, $title 
                 [, $description             = $title as Default
                  , $high_quailty_music_url  = $music_url as Default
                 ] 
             );
  

• Rich Message

    {String} WeChatServer::getXml4RichMsgByArray(
                array(
                    array(
                        'title' => # title
                        'desc'  => # description
                        'pic'   => # picture url
                        'url'   => # article url
                    )
                    [, ... ]
                )
             );
  

DEMO CODE

<?PHP
    include('WeChatServer.php');
    function responseTxt( $postObj ){
        $content = $postObj['content'];
        echo WeChatServer::getXml4Txt( "You say : [$content]." );
    }

    $svr = new WeChatServer( 
      'token_in_admin.wechat.com', 
      array(
        'receiveAllStart'  => function( $postObj ){ 
            log( $postObj['from'] );
            // log who sent this msg
            // if u want to send response here,
            //      please exit
            // echo WeChatServer::getXml4Txt( 'Hey' );
            // exit();
        },
        'receiveMsg::text' => 'responseTxt'
      )
    );

###WeChatClient.php

About

WeChatClient is used to set/get user-defined menu in chat, manage followers group, upload/download media file and send customer server messages.

getting start

<?PHP
    include( 'WeChatClient.php' );
    # If you are the user of mp.weixin.qq.com, please include WeChatClient.zh_CN.php
    # include( 'WeChatClient.zh_CN.php' ); 
    $client = new WeChatClient( 'your-appid', 'your-appsecret' );

Access Token

• wiki

<?PHP
    # If you need access token, you can use following:
    $client->getAccessToken(); 

    # If you need access token with expire time, use:
    $tokenOnly = 0;
    $client->getAccessToken( $tokenOnly ); 
    # @return array(
    #             'token'  => /* access token */,
    #             'expire' => /* timestamp */
    #         )

    # access token info will be cached
    #   once $client->getAccessToken is called

    $client->setAccessToken( $tokenInfo );
    # Cached accesstoken, $tokenInfo = $client->getAccessToken( 0 );

User-defined Menu

Menu Create Wiki

<?PHP
    # Get Menu Array or null for empty;
    $client->getMenu();

    # Delete Menu as you see
    $client->deleteMenu();

    #
    $client->setMenu( $menu )
    # @param $menu {Array|String}
    #   When use String: $menu should be Json String
    #   When use Array:  Make sure 
    #      1) Your PHP Version support json_encode JSON_UNESCAPED_UNICODE
    #   OR 2) Don't use Unicode Chars.

Manage Followers & Group

• Group Management API
• User profile

<?PHP

    $client->getUserInfoById( $userid [, $lang='en' ] );
    # @return {Array} For detail 
    #       @see http://admin.wechat.com/wiki/index.php?title=User_Profile

    $client->getFollowersList( [ $next_id = '' ] );
    # @return {Array}   array(
    #                       'total'   => {int},
    #                       'list'    => array( userid1, userid2 ... )
    #                       'next_id' => {string}
    #                   )
    # if total length > list length, you can use
    $client->getFollowersList( $next_id );
    
    $client->createGroup( $name );
    # @return {int|null} group id OR null for failure

    $client->renameGroup( $groupid, $name);
    # @return {boolen}

    $client->moveUserById( $userid, $groupid )
    # @return {boolen}

    $client->getAllGroups();
    # @return {Array|Null}

    $client->getGroupidByUserid( $userid );
    # @return {int}

Media File

• wiki

<?PHP
    $client->upload( $type, $file_path [, $mediaidOnly = true ] );
    # @param $type {string} image | voice | video | thumb
    # @return {string} When $mediaidOnly = true, return media id
    # @return {Array} When $mediaidOnly = false, 
    #       return array( 'type' =>, 'media_id' =>, 'create_at' => /* timestamp */)

    $client->download( $media_id );
    # @return media file binary data

Customer Server Message

• wiki

<?PHP
    # all the following will return {boolen}
    $client->sendTextMsg( $user_id, $txt );
    $client->sendImgMsg( $user_id, $media_id );
    $client->sendVoice( $user_id, $media_id );
    $client->sendVideo( $user_id, $media_id, $title, $description );
    $client->sendMusic( 
        $user_id, $music_url, $thumb_media_id, $title 
        [, $description = $title, $high_quality_music_url = $music_url ] 
    );
    $client->sendRichMsg( 
        $user_id, 
        array(
            array(
                'title'     => /* article title */,
                'desc'      => /* description */,
                'url'       => /* article url */,
                'thumb_url' => /* thumb url */,
            )
            [ , ... ]
        ) 
    );

Qrcode

• wiki

<?PHP
    $client->getQrcodeTicket( [ $options ] );
    # @param $options {Array}
    #       array(
    #           'scene_id'   => /* default = 1*/
    #           'expire'     => /* default = 0 mean no limit */
    #           'ticketOnly' => /* default = true */
    #       )
    # @return {string|null} when ticketOnly = true, return ticket string
    # @return {array|null}  when ticketOnly = false, 
    #       return array( 
    #                   'ticket' => /* ... */,  
    #                   'expire' => /* ... */ 
    #              )

    WeChatClient::getQrcodeImgUrlByTicket( $ticket )
    # @return {string} 

    WeChatClient::getQrcodeImgByTicket( $ticket )
    # @return Image Binary