Download the PHP package garbetjie/wechat without Composer

WeChat PHP SDK

This is a simple PHP library for interacting with the official WeChat APIs. It was created to remove some of the complexity around interacting with the WeChat API.

Table of contents

1. Installation
2. Basic usage
3. Authentication
4. Groups
5. Media
6. Menus
7. QR

1. Installation

You can use composer to install:

composer require garbetjie/wechat

Requires PHP 5.6+.

2. Basic usage

All available functionality has been split out into separate services. Each of these services require a Garbetjie\WeChatClient\Client instance. This client instance should be passed into the service when instantiating:

3. Authenticating

Before any interacting with the WeChat API can take place, an access token will be needed. The Authentication service can be used to acquire an access token:

Once you have authenticated, all further API calls made will have your access token automatically injected as part of the request.

Caching access tokens

There are a limited number of access tokens that can be retrieved for an OA in any given day. For this reason (and for performance reasons), it is a good idea to cache these access tokens. There are a number of storage mechanisms that are options available for caching access tokens.

If no storage is specified, a default of storing the access tokens on the file system in the sys_get_temp_dir() directory.

File system

Memcached

MySQL

The MySQL storage adapter can have the table name, as well as the column names customised. This will allow you to ensure the storage of access tokens fits into your current database structure.

Custom interfaces

You can write any custom interfaces you'd like to be able to store access tokens. Any of these custom storage adapters need to simply implement the Garbetjie\WeChatClient\Authentication\Storage\StorageInterface interface.

4. Groups

User group management is done through the Garbetjie\WeChatClient\Groups\Service. Authentication is required in order to view and modify groups.

When creating, modifying or retrieving groups from the API, instances of Garbetjie\WeChatClient\Groups\Group will be returned.

Create a group

Modify a group

Remove a group

Fetch all groups.

Fetch a single group.

In reality, this is a thin wrapper around the Garbetjie\WeChatClient\Groups\GroupsService::getAllGroups() method call, that makes it easier to fetch a single group.

5. Media

Media items need to be stored on WeChat's servers before they're able to be sent as messages to users. Both the uploading and downloading of media items is possible using the Garbetjie\WeChatClient\Media\Service service.

Creating a new instance

Uploading a file

Downloading a media item.

There are 3 different way of downloading a media item:

1. Into a file (pass the path as the $into parameter).

2. Into an already-opened stream (pass a stream into the $into parameter).

3. Or into a temporary stream (don't pass anything for the $into parameter) created by the tmpfile() function.

Available media types

Thumbnails

Required when uploading a news article. The media ID returned here needs to be used when adding a news article. Supports JPG images only, no larger than 64KB.

News

This is used when sending a multi-story news article in a broadcast message. It will need to be uploaded first, and the resultant message ID will need to be used when sending the broadcast message.

Audio

Used when sending a snippet of audio to the user. Supported types are AMR and MP3 audio files, no larger than 2MB.

Image

Used to send an image to a user. Supports BMP, PNG, JPEG, JPG or GIF extensions, no larger than 2MB.

Video

Send a video to a user. Supports MP4 format, no larger than 10MB in size.

6. Menus

Menus that are displayed within an official account can be customised via the WeChat API. The Garbetjie\WeChatClient\Menu\MenuService services enables the modification of this menu:

7. QR Codes

QR codes can be generated via the WeChat API. There are two kinds of QR codes that are available: temporary codes, and permanent codes.

Temporary codes expire after a developer-determine time period (maximum of 30 days), whereas permanent codes never expire. However, an official account is limited to having 100,000 permanent codes active at any given time.

Creating a temporary QR code

When creating a temporary QR code, you are limited to a QR code value of a number, in the range of 1 to 100,000. If no expiry time is given, the generated QR code will expire after 30 seconds. You can specify an expiry time of up to 2 592 000 seconds (30 days).

Creating a permanent QR code

Permanent QR codes are limited to 100,000 of them, and do not have an expiry date. You can use either a numeric value (in the range of 1 to 100,000), or you can use a string value of up to 64 characters long.

Terminology

OA

Official Account. This is basically the responder of a client.

User

The user of WeChat. Also known as a follower, this is the end user that is accessing the OA from their mobile device, desktop application or web interface.

Callback messages

Immediate responses (in XML) in response to a keyword sent by the follower. If reply within 5 seconds cannot be gauranteed, then an empty response ( like die() ) should be returned, and a customer service (push) message should be sent.

Customer Service ( Push ) messages

Also known as a push message, this is an asynchronous response made by the OA to the user. Push messages can only be made for 48 hours after a user has interacted with the OA.