Skip to content

froger-me/wp-weixin

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

56 Commits
css
css
 
 
images
images
 
 
inc
inc
 
 
js
js
 
 
languages
languages
 
 
lib
lib
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 
functions.php
functions.php
 
 
readme.txt
readme.txt
 
 
uninstall.php
uninstall.php
 
 
wp-weixin.php
wp-weixin.php
 
 

Repository files navigation

WP Weixin - WordPress WeChat integration

General Description

WP Weixin provides integration between WordPress and WeChat. Register or authenticate users automatically in WeChat browser, use WeChat to create an account or authenticate on computers by scanning a QR code with WeChat, share posts in WeChat Moments and conversations or extend the plugin for more features!

Companion Plugins

Developers are encouraged to build plugins and themes integrated with WeChat with WP Weixin as a core, leveraging its publicly available functions, actions and filters, or directly make use of the provided SDK.

If you wish to see your plugin added to this list, please contact the author.

Important Notes

  • Requires a China Mainland WeChat Official Account (Subscription or Service - Service is required if used with companion plugins dealing with payments).
  • A domain used by WordPress must be registered in an Official Account's backend
  • The plugin itself does not require programming knowledge, and provides really useful functionalities out of the box. Where it really shines though is when used by developers to extend its functionalities (mainly through the pre-initialised JS SDK, the WeChat Responder, and various provided functions, actions and filters).

Registering a domain in the Official Account's backend

To register a domain and authorize communication between it and the WeChat APIs (frontend JS and server side), the domain must be linked with an ICP license first. Then, on https://mp.weixin.qq.com:

  • connect to the Official Account's backend
  • click the "Interface Privilege" menu item
  • in the list, search for "Web Page Authorization" and click the "Modify" link
  • add the domain in both "JS interface security domain name" and "Webpage authorization domain name" by clicking the "Set-up" link for both sections (without the protocol http or https) - making sure to include the MP_verify_[some_code].txt files to the root of the website corresponding to the domain registered as instructed, accessible publicly.

Overview

This plugin adds the following major features to WordPress:

  • WP Weixin settings page: configure the plugin with an Official Account (or as many as you want in multisite) in English or Chinese out of the box, with instructions for each option.
  • WeChat Authentication: automatically create and authenticate users in WordPress in the WeChat browser, or allow users to scan a QR code with WeChat when using classic browsers (social login).
  • WeChat Account Binding: let users bind/unbind their existing WordPress account with their WeChat account. Integrated with WooCommerce and Ultimate Member account pages, and may be integrated with any membership/account/profile plugin easily.
  • WeChat Share: Share posts and pages on Moments or Send to chat, in a pretty way. Triggers JavaScript events for developers on success and failure.
  • Force WeChat mobile: to prevent users from browsing the website outside of the WeChat browser. If accessed with a classic browser, the page displays a QR code.
  • Force following the Official Account: to harvest WeChat followers, forcing users to follow the Official Account before accessing the content.
  • WordPress Users screen override: to display WeChat names and WeChat avatars if they exist, instead of the default values in the user screen.
  • WP Weixin QR code generator: to create custom codes.
  • Menu integration: allows to set the Official Account menus in WordPress when the WeChat Responder is enabled.
  • Welcome message: sends a welcome message in WeChat when a user follows the Official Account ; allows to do so with WordPress when the WeChat Responder is enabled.
  • Developers - WeChat Responder: for developers to receive and respond to calls made by WeChat's API.
  • Developers - WeChat JS_SDK: the wx JavaScript global variable is pre-configured with a signed package to leverage the JavaScript SDK of WeChat in WordPress themes more easily.

Compatible with WooCommerce, WooCommerce Multilingual, WPML, Ultimate Member, WordPress Multisite, and many caching plugins.

Object Cache considerations

This plugin uses WordPress WP_Object_Cache to optimise the number of database queries, ensuring only the proper amount is fired on each page load. Because the WP_Object_Cache object can be affected by third-party plugins, it is required that such plugins implement the wp_cache_add_non_persistent_groups function to avoid side effects.

See below examples of popular cache plugins compatible with WP Weixin:

Settings

The following settings are available on the WP Weixin settings page.

Main Settings

Required settings below are the minimal configuration necessary for the plugin to have any effect.

Name Required Type Description
Enable Yes checkbox Enable WP Weixin - requires a valid configuration.
WeChat App ID Yes text The AppId in the backend at https://mp.weixin.qq.com/ under Development > Basic configuration.
WeChat App Secret Yes text The AppSecret in the backend at https://mp.weixin.qq.com/ under Development > Basic configuration.
WeChat OA Name No text The name of the Official Account (recommended to enter the actual name).
WeChat OA Logo URL No text A URL to the logo of the Official Account - (recommended enter the URL of a picture of the actual logo).
Enable WeChat authentication No checkbox If enabled, users will be authenticated with their WeChat account in WordPress when visiting the site with the WeChat browser(if not, a session cookie with key 'wx_openId-' . apply_filters( 'wp_weixin_ms_auth_blog_id', 1 ) is set).
Force WeChat mobile No checkbox Make the website accessible only through the WeChat browser.
If accessed with another browser, the page displays a QR code.
Force follow (any page) No checkbox Require the user to follow the Official Account before accessing the site with the WeChat browser.

Multisite Settings

These settings are hidden by default and only available when:

  • WordPress Multisite is installed
  • The current user has the manage_network_options capability

They affect the entire multisite network.

Name Type Description
Force a blog for authentication select Replaced by an info text if a callback is hooked to wp_weixin_ms_auth_blog_id.
Blog to use as proxy when authenticating users.
Force a blog for WeChat payments select Replaced by an info text if a callback is hooked to wp_weixin_ms_pay_blog_id.
Remains hidden if "Use merchant platform" option is not checked (needs WeChat payment integrated in a companion plugin).
Blog to use as proxy when processing payments. If default, the JSAPI Payment Authorization URLs must be entered for all the blogs of the network doing payments, and the QR Payment callback URL must be capable of handling all the notifications coming from WeChat Pay API.

WeChat Responder Settings

Name Type Description
Use WeChat Responder checkbox Allow the website to receive messages from WeChat and respond to them. Server configuration must be enabled and configured in https://mp.weixin.qq.com/ under Development > Basic configuration. Required if using "Force follow" option in the Main Settings or WeChat Pay settings.
WeChat Token text The Token in the backend at https://mp.weixin.qq.com/ under Development > Basic configuration.
Encode messages checkbox Encode the communication between the website and the WeChat API (recommended).
WeChat AES Key text The EncodingAESKey in the backend at https://mp.weixin.qq.com/ under
Development > Basic configuration.
Send welcome message checkbox Send a welcome message when a user follows the Official Account.
The following filters can be used to change the default values of the message:
Welcome message image URL text A URL to the image used for the welcome message sent after a user follows the Official Account (external or from the Media Library).
Default image is in /wp-weixin/images/default-welcome.png.

WeChat Pay Settings

These settings are hidden by default and only available if a WeChat Pay integration plugin such as WP Weixin Pay or Woo WeChatPay is installed and activated (this behavior may be altered using the wp_weixin_show_settings_section filter).

Name Type Description
Use merchant platform checkbox Allow users to send money to the Service Account with WeChat - an account at https://pay.weixin.qq.com/ is necessary. This setting is not configurable (forced to checked and hidden) if Woo WeChatPay plugin is activated. 
WeChat Merchant App ID text The AppID in the backend at https://pay.weixin.qq.com/ - can be different from the WeChat App ID as the WeChat Pay account may be linked to a different AppID. Leave empty to use the WeChat App ID.
WeChat Merchant ID text The Merchant ID in the backend at https://pay.weixin.qq.com/index.php/extend/pay_setting.
PEM certificate prefix text The prefix of the certificate files downloaded from https://pay.weixin.qq.com/index.php/core/cert/api_cert.
Certificate files default prefix is apiclient (for apiclient_cert.pem and apiclient_key.pem files).
Required notably to handle refunds through WeChat Pay.
PEM certificate files path text The absolute path to the containing folder of the certificate files downloaded from https://pay.weixin.qq.com/index.php/core/cert/api_cert on the current file system.
Example: /home/user/wechat-certificates.
Must have read permissions for the user running PHP, and located outside of the web root.
Required notably to handle refunds through WeChat Pay.

In addition to these settings, the plugin provides onscreen help for what values to input for the different URLs in the merchant account's API configuration screen.

Proxy Settings

Name Type Description
Use a proxy checkbox Enable proxy.
Proxy Host text IP address or URI of the proxy host.
Proxy Port text Port to use to connect to the proxy host.

Depending on your server configuration, a proxy may be needed if WordPress is behind a firewall or within a company network.

Miscellaneous Settings

Name Type Description
Show WeChat name and picture in Users list page checkbox Override the display of the WordPress account names and avatars.
Show WeChat public info checkbox Show the WeChat public information on user profile pages. Integrates with WooCommece and Ultimate Member.
Show WeChat Account binding link checkbox Show a link to bind or unbind a WordPress account with a WeChat account on user profile pages. Integrates with WooCommece and Ultimate Member.
Show WeChat Account authentication link checkbox Show a link to authenticate via QR code using a WeChat account on the WordPress login form.
Official Account menu language awareness checkbox Customise the menu of the Official Account depending on user's language. By default, the language of the menu corresponding to the website's default language is used.
This setting is only available if WPML is activated.
Use custom persistence for access_token checkbox Use a custom persistence method for the Official Account access_token and its expiry timestamp.
Warning - requires the implementation of:The parameter $access_info is an array with the keys token and expiry.
Add the hooks above in a plugins_loaded action with a priority of 5 or less.
Useful to avoid a race condition if the access_token information needs to be shared between multiple platforms.
When unchecked, access_token & expiry timestamp are stored in the WordPress options table in the database.

Multisite

WP Weixin supports multisite installs of WordPress, wether using domain/subdomains or subdirectories. WP Weixin needs to be configured with the same settings and enabled on all the blogs where authentication is needed for a given Official Account.

With WeChat mobile authentication enabled, users visiting one of the blogs are automatically registered to the network, and added to the visited blog with the blog's default user role. Users are also automatically added to other blogs of the network upon visit when already registered on one of the blogs. This behavior can be changed with the wp_weixin_ms_auto_add_to_blog filter, for example if some of the blogs should not accept pre-authenticated WeChat users.

When using a domain/subdomain-based network of blogs, the main blog's domain/subdomain is used for cross-domain authentication. The behavior can be changed with the setting "Force a blog for authentication" in the Multisite Settings section of the plugin's page.

WeChat Pay integrated plugins can also support domain/subdomain-based network installs of WordPress Multisite by leveraging the functions, actions and filters provided by WP Weixin. The blog used for payment can be forced with the "Force a blog for WeChat payments" in the Multisite Settings section of the plugin's page.
WP Weixin Pay and Woo WeChatPay are examples of plugins integrated with WeChat Pay, working no matter the type of Multisite installation (subdirectory or domain/subdomain).

Unlike some plugins (commercial, obfuscated, and with dubious security standards), WP Weixin does not and will not rely on a crossdomain script dumped at the root of WordPress, but prefers to leverage the WordPress actions and filters.

It is possible to use the plugin with multiple Official Accounts on the same network, as long as the developer leverages wp_weixin_ms_auth_blog_id and wp_weixin_ms_pay_blog_id filter hooks to account for the different possible scenarios (see a simple example plugin here).

WeChat SDK

One of the most poweful tools provided by WP Weixin is its PHP Wechat Software Development Kit. To get an instance of the WeChat SDK, developers can use the following snippet:

$wechat_sdk = wp_weixin_get_wechat();

The returned value is an instance of WP_Weixin_Wechat, which is a wrapper class for Wechat_SDK: it ensures all settings and tokens are valid and initialised. Developers are discouraged from using the Wechat_SDK class directly.

All the public methods of Wechat_SDK are callable through the WP_Weixin_Wechat object and should be used only for advanced purposes. These are low level methods compared to the provided functions: the latter should be used where possible, and developers should only use the SDK if no function achieving the intended result exists.
For the public methods available, please refer to the source code of Wechat_SDK directly.

Quick, non-optimised example of advanced use - do something with the list of followers' openIDs, with error handling:

$wechat      = wp_weixin_get_wechat();
$next_openid = true;
$result      = $wechat->users();
$error       = $wechat->getError();

// Warning - will loop until WeChat stops providing results ; do not use in production 
while ( false !== $next_openid && ! $error ) {

	if ( is_array( $result ) ) {
		$next_openid = ( ! empty( $result['next_openid'] ) ) ? $result['next_openid'] : false;

		// Do something with the returned data
		do_something( $result['data'] );
	} else {
		$next_openid = false;
	}

	if ( $next_openid ) {
		$result = $wechat->users( $next_openid );
		$error  = $wechat->getError();
	}
}

if ( $error ) {
	// Handle the error with the array containing the error information
	handle_error( $error );
}

Functions

The functions listed below are made publicly available by the plugin for theme and plugin developers. Although the plugin's main classes can theoretically be instanciated without side effect if the $hook_init parameter is set to false, it is recommended to use only the following functions as there is no guarantee future updates won't introduce changes of behaviors.

Functions index:

wp_weixin_is_wechat

wp_weixin_is_wechat();

Description
Wether the visitor is using the WeChat browser.

Return value

(bool) Wether the vistor is using the WeChat browser.

wp_weixin_ajax_safe

wp_weixin_ajax_safe();

Description
Call this function in a WordPress ajax action. Allow interactions with WeChat API during an ajax request.

wp_weixin_get_user_by_openid

wp_weixin_get_user_by_openid( string $openid );

Description
Get a WordPress user by WeChat openID.

Parameters
$openid

(string) A WeChat openID.

Return value

(mixed) A WP_User if a WordPress user bound with a corresponding WeChat openID exists, false otherwise.

wp_weixin_get_user_by_unionid

wp_weixin_get_user_by_unionid( string $unionid, int $blog_id = false );

Description
Get a WordPress user by WeChat unionID, or a collection of WordPress users if several matches exist (possible only in the case of Multisite with multiple Official Accounts).

Parameters
$unionid

(string) A WeChat unionID.

Return value

(mixed) A WP_User object if a WordPress user with a corresponding WeChat unionID exists, an array of WP_User objects if several matches exist, false otherwise.

wp_weixin_get_wechat

wp_weixin_get_wechat();

Description
Get an instance of WP_Weixin_Wechat (wrapper object for Wechat_SDK - see WeChat SDK).

Return value

(WP_Weixin_Wechat) An instance of the wrapper object for Wechat_SDK.

wp_weixin_get_options

wp_weixin_get_options();

Description
Get all the options used to configure the plugin.

Return value

(array) An associative array with all the options used to configure the plugin.

wp_weixin_get_option

wp_weixin_get_option( $key );

Description
Get a specific option value used to configure the plugin.

Parameters
$key

(string) The option key.

Return value

(mixed) A string, boolean, or integer if the option has a value, null otherwise.

wp_weixin_wpml_switch_lang

wp_weixin_wpml_switch_lang( $force = true );

Description
If WPML is active and the current user's WeChat language is known, switch the language to the value provided by the user's WeChat account.
Uses SitePress::switch_lang( $code = null, $cookie_lang = false ) - it is up to the developer to get up to speed with WMPL code base and documentation.

Parameters
$force

(bool) If set to true, will always switch the language ; if false, the language will be switched only if "Browser language redirect" is enabled in WPML - default true.

Return value

(bool) Wether SitePress::switch_lang( $code = null, $cookie_lang = false ) was called.

wp_weixin_get_signed_package

wp_weixin_get_signed_package();

Description
Get a WeChat signed package to use with the WeChat JSAPI.
Note: the JavaScript global variable wx is already properly signed and initialised with the complete jsApiList if the wp-weixin-main-script is already enqueued.
See the "JavaScript" section of the documentation for more details.

Return value

(array) The signed package to pass to a script via wp_localize_script( $handle, $object_name, $l10n ).

wp_weixin_get_user_wechat_info

wp_weixin_get_user_wechat_info( int $user_id = false, bool $output = false );

Description
Get a user's WeChat information. Gets the current user's if the user ID is omitted.

Parameters
$user_id

(int) The ID of the user - default false.

$output

(bool) Wheter to output the information (using the wp-weixin-public-info template) - default false.

Return value

(mixed) An array of WeChat information if exists, false otherwise.

wp_weixin_get_user_wechat_openid

wp_weixin_get_user_wechat_openid( int $user_id = false );

Description
Get a user's WeChat openID. Gets the current user's if the user ID is omitted.

Parameters
$user_id

(int) The ID of the user - default false.

Return value

(mixed) A WeChat openID if exists, false otherwise.

wp_weixin_get_auth_link

wp_weixin_get_auth_link( bool $output = false, string $target = '', $class = '' );

Description
Get a link to the WeChat authentication page.
This function has no effect in the WeChat browser.

Parameters
$output

(bool) Wether to output the link.

$target

(string) The target of the link.

$target

(string) The CSS class of the link.

Return value

(mixed) If $output is set to true, the link's markup - false otherwise.

wp_weixin_get_bind_link

wp_weixin_get_bind_link( bool $output = false, string $target = '_blank' );

Description
Get a link to the WeChat account binding page.
This function has no effect in the WeChat browser.

Parameters
$output

(bool) Wether to output the link.

$target

(string) The target of the link.

Return value

(mixed) If $output is set to true, the link's markup - false otherwise.

wp_weixin_unbind

wp_weixin_unbind( int $user_id, string $open_id = '' );

Description
Unbind a WordPress user account previously bound with WeChat, effectively deleting all the recorded information related to the associated WeChat account.
Note: a WeChat-only WordPress user account is a WordPress account that was created automatically by WP Weixin when opening the website in WeChat browser (Username following the wx-[openid] pattern).
If a user_id corresponding to a WeChat-only WordPress user account that may or may not have been previously bound is provided (Username following the wx-[openid] or wx-bound-[openid] pattern), the Username is updated with the wx-unbound-[openid] pattern.

Parameters
$user_id

(int) The ID of the user.

$open_id

(string) The openID of the WeChat account - if left empty, set to the current user's recorded value.

Return value

(bool) Wether the account was unbound.

wp_weixin_bind

wp_weixin_bind( int $user_id, string $openid );

Description
Bind a WordPress user account with WeChat, effectively overwritting all the recorded information related to an associated WeChat account if exist.
Note: a WeChat-only WordPress user account is a WordPress account that was created automatically by WP Weixin when opening the website in WeChat browser (Username following the wx-[openid] pattern).
A WeChat-only WordPress user account with the provided $openid recorded must exist.
If a value for $user_id corresponding to a WeChat-only WordPress user account that may or may not have been previously unbound is provided (Username following the wx-[openid] or wx-unbound-[openid] pattern), the Username is updated with the wx-bound-[openid] pattern.
A given openID cannot be used to bind WeChat with multiple WordPress user accounts.

Parameters
$user_id

(int) The ID of the user.

$open_id

(string) The openID corresponding to a WeChat-only WordPress user account.

Return value

(bool) Wether the account was bound.

wp_weixin_is_follower

wp_weixin_is_follower( int $user_id );

Description
Check whether the user with ID $user_id is a follower of the WeChat Official Account.

Parameters
$user_id

(int) The ID of the user.

Return value

(bool) Wether the user follows the WeChat Official Account.

Hooks - actions & filters

WP Weixin gives developers the possibilty to customise its behavior with a series of custom actions and filters.

Actions

Actions index:

wp_weixin_extensions

do_action( 'wp_weixin_extensions', mixed $wechat, mixed $wp_weixin_settings, mixed $wp_weixin, mixed $wp_weixin_auth, mixed $wp_weixin_responder, mixed $wp_weixin_menu );

Description
Fired when WP Weixin is fully loaded and if "Enabled" is checked in WP Weixin Main Settings. Typically used to build plugins using WP Weixin as a core.
Note: it is recommended to use the provided functions where possible instead of the methods of this action's parameters, as there is no guarantee future updates won't introduce changes of behaviors.

Parameters
$wechat

(mixed) A WP_Weixin_Wechat object.

$wp_weixin_settings

(mixed) A WP_Weixin_Settings object.

$wp_weixin

(mixed) A WP_Weixin object.

$wp_weixin_auth

(mixed) A WP_Weixin_Auth object.

$wp_weixin_responder

(mixed) A WP_Weixin_Responder object if the WeChat Responder is enabled, false otherwise.

$wp_weixin_menu

(mixed) A WP_Weixin_Menu object if the WeChat Responder is enabled, false otherwise.

wp_weixin_responder

do_action( 'wp_weixin_responder', array $request_data );

Description
Fired after receiving a request from WeChat.

Parameters
$request_data

(array) The data sent in the request from WeChat.

wp_weixin_save_access_info

do_action( 'wp_weixin_save_access_info', array $access_info );

Description
Fired after renewing the Official Account access_token if custom persistence is used. Used to save the access information - particularly useful to avoid a race condition if the access_token needs to be shared between multiple platforms.

Parameters
$access_info

(array) The access information in an associative array. Keys are token and expiry.

wp_weixin_before_user_profile_wechat_info

do_action( 'wp_weixin_before_user_profile_wechat_info', mixed $wechat_info, mixed $user );

Description
Fired before displaying WeChat public info on the user profile.

Parameters
$wechat_info

(mixed) An array of WeChat public info to display on the user profile if they exist, false otherwise.

$user

(mixed) A WP_User object if the user exists, false otherwise.

wp_weixin_after_user_profile_wechat_info

do_action( 'wp_weixin_after_user_profile_wechat_info', mixed $wechat_info, mixed $user );

Description
Fired after displaying WeChat public info on the user profile.

Parameters
$wechat_info

(mixed) An array of WeChat public info displayed on the user profile, false otherwise.

$user

(mixed) A WP_User object if the user exists, false otherwise.

wp_weixin_before_bind_account

do_action( 'wp_weixin_before_bind_account', int $user_id, int $wechat_user_id, array $wechat_user_blog_ids, int $current_blog_id );

Description
Fired before binding a WordPress user account with WeChat.

Parameters
$user_id

(int) The user ID.

$wechat_user_id

(int) ID of a WeChat-only WordPress user account (Username following the wx-[openid] pattern).

$wechat_user_blog_ids

(array) List of blog IDs the WeChat-only WordPress user account belongs to.

$current_blog_id

(int) The blog ID of the current blog.

wp_weixin_after_bind_account

do_action( 'wp_weixin_after_bind_account', bool $bound, int $user_id, int $wechat_user_id, array $wechat_user_blog_ids, int $current_blog_id );

Description
Fired after binding a WordPress user account with WeChat.

Parameters
$bound

(bool) Wether the WordPress user account was successfully bound with WeChat.

$user_id

(int) The user ID.

$wechat_user_id

(int) ID of a WeChat-only WordPress user account (Username following the wx-[openid] pattern).

$wechat_user_blog_ids

(array) List of blog IDs the WeChat-only WordPress user account belongs to.

$current_blog_id

(int) The blog ID of the current blog.

wp_weixin_before_unbind_account

do_action( 'wp_weixin_before_unbind_account', int $user_id, string $openid );

Description
Fire before unbinding a WordPress user account from WeChat.

Parameters
$user_id

(int) The user ID.

$openid

(string) The WeChat openID.

wp_weixin_after_unbind_account

do_action( 'wp_weixin_after_unbind_account', bool $unbound, int $user_id, string $openid );

Description
Fire after unbinding a WordPress user account from WeChat.

Parameters
$unbound

(bool) Wether the WordPress user account was successfully unbound from WeChat.

$user_id

(int) The user ID.

$openid

(string) The WeChat openID.

wp_weixin_before_tabs_settings

do_action( 'wp_weixin_before_tabs_settings' );

Description Fired before outputting the tabs of the WP Weixin page.

wp_weixin_before_main_tab_settings

do_action( 'wp_weixin_before_main_tab_settings' );

Description Fired before outputting the main settings tab of the WP Weixin page.

wp_weixin_before_main_settings_inner

do_action( 'wp_weixin_before_main_settings_inner' );

Description Fired before outputting the main settings content on the WP Weixin page.

wp_weixin_after_main_settings_inner

do_action( 'wp_weixin_after_main_settings_inner' );

Description Fired after outputting the main settings content on the WP Weixin page.

wp_weixin_after_main_tab_settings

do_action( 'wp_weixin_after_main_tab_settings' );

Description Fired after outputting the main settings tab of the WP Weixin page.

wp_weixin_before_qr_tab_settings

do_action( 'wp_weixin_before_qr_tab_settings' );

Description Fired before outputting the QR code generator tab of the WP Weixin page.

wp_weixin_after_qr_tab_settings

do_action( 'wp_weixin_after_qr_tab_settings' );

Description Fired after outputting the QR code generator tab of the WP Weixin page.

wp_weixin_after_tabs_settings

do_action( 'wp_weixin_after_tabs_settings' );

Description Fired after outputting the tabs of the WP Weixin page.

wp_weixin_before_settings

do_action( 'wp_weixin_before_settings' );

Description Fired before outputting the settings on the WP Weixin page.

wp_weixin_before_main_settings

do_action( 'wp_weixin_before_main_settings' );

Description Fired before outputting the main settings box on the WP Weixin page.

wp_weixin_after_main_settings

do_action( 'wp_weixin_after_main_settings' );

Description Fired after outputting the main settings box on the WP Weixin page.

wp_weixin_before_qr_settings

do_action( 'wp_weixin_before_qr_settings' );

Description Fired before outputting the QR code generator on the WP Weixin page.

wp_weixin_before_qr_settings_inner

do_action( 'wp_weixin_before_qr_settings_inner' );

Description Fired before outputting the QR code generator box on the WP Weixin page.

wp_weixin_after_qr_settings_inner

do_action( 'wp_weixin_after_qr_settings_inner' );

Description Fired after outputting the QR code generator box on the WP Weixin page.

wp_weixin_after_qr_settings

do_action( 'wp_weixin_after_qr_settings' );

Description Fired after outputting the QR code generator on the WP Weixin page.

wp_weixin_after_settings

do_action( 'wp_weixin_after_settings' );

Description Fired after outputting the settings on the WP Weixin page.

wp_weixin_endpoints

do_action( 'wp_weixin_endpoints' );

Description
Fired when adding WP Weixin rewrite rules. Useful for companion plugins to add their own, and make sure they are registered properly (rules are flushed when WP Weixin settings are saved).

wp_weixin_handle_payment_notification

do_action( 'wp_weixin_handle_payment_notification' );

Description
Fired when handling a WeChat Pay transaction notification.

Fired last by WP Weixin (PHP_INT_MIN) ; should be fired earlier by companion plugins integrating with WeChat Pay.
See a WeChat Pay integration plugin skeleton for how to handle WeChat Pay notifications.

wp_weixin_handle_auto_refund

do_action( 'wp_weixin_handle_auto_refund', mixed $refund_result, array $payment_result );

Description
Fired after an automatic refund for a failed transaction has been attempted.

See a WeChat Pay integration plugin skeleton for how to handle WP Weixin automatic refund results.

Parameters
$refund_result

(mixed) An array containing the WeChat Pay API's response in case the refund wass successful, false otherwise.

$payment_result

(array) A payment notification result. Structure of a result:

array(
	'success'      => false,    // optional - (bool) wether the transaction to handle was found ; default false
	'data'         => $data,    // required - (array) return value of WP_Weixin_Wechat::getNotify()
	'refund'       => false,    // optional - (mixed) false if no refund needed, true or an refund message for the user otherwise ; default false
	'notify_error' => false,    // optional - (mixed) false if no error, true or an error message otherwise ; if truthy and pay_handler set to true, WeChat Pay API will continue to send notifications for the transaction ; default false
	'blog_id'      => $blog_id, // required for multisite, optional otherwise - (int) the ID of the blog where the original transaction was made ; default the return value of get_current_blog_id()
	'pay_handler'  => false,    // optional - (bool) wether the result is for the callback registered in the WeChat Pay backend ; default false
	/* More custom items can safely be added to the array */
);

Filters

Filters index:

wp_weixin_browser_page_qr_src

apply_filters( 'wp_weixin_browser_page_qr_src', string $src );

Description
Filter the source of the QR code to show on classic browsers for a page only accessible through WeChat browser.

Parameters
$src

(string) The source of the QR code to show on classic browsers.

wp_weixin_subscribe_src

apply_filters( 'wp_weixin_subscribe_src', string $src );

Description
Filter the source of the QR code used to follow the Official Account.

Parameters
$src

(string) The source of the QR code.

wp_weixin_follower_notice_title

apply_filters( 'wp_weixin_follower_notice_title', string $title );

Description
Filter the title of the page displaying the QR code to follow the Official Account.

Parameters
$title

(string) The title of the page - default "Follow Us!".

wp_weixin_follower_notice

apply_filters( 'wp_weixin_follower_notice', string $notice );

Description
Filter the message displayed on the page displaying the QR code to follow the Official Account.

Parameters
$notice

(string) The displayed message - default "Please scan this QR Code to follow us before accessing this content.".

wp_weixin_auth_needed

apply_filters( 'wp_weixin_auth_needed', bool $needs_auth );

Description
Wether the URL needs the user to be authenticated using WeChat. When "Enable WeChat authentication" is checked in the settings, URLs triggering WordPress's init action hook need authentication by default, unless they are whitelisted using this filter. By default, all the admin pages, the WP Weixin classic browser authentication page, the WordPress ajax endpoint, the WeChat responder endpoint, and the WooCommerce API endpoints are whitelisted and accessible outside WeChat.

Parameters
$needs_auth

(bool) Wether authentication is needed to visit the URL.

wp_weixin_debug

apply_filters( 'wp_weixin_debug', bool $debug );

Description
Filter wether to activate debug mode (PHP error logs, JavaScript console messages, JavaScript alerts).

Parameters
$debug

(bool) Wether debug mode is activated - default WP_DEBUG constant value.

wp_weixin_follower_welcome_title

apply_filters( 'wp_weixin_follower_welcome_title', string $title, mixed $before_subscription );

Description
Filter the title of the message the user receives when following the Official Account.

Parameters
$title

(string) The title - default "'Welcome user_name!'" where user_name is the user's WeChat Name.

$before_subscription

(mixed) If numeric, the WP_Post ID of the last page the user was visiting ; if string, the URL of the last page the user was visiting - default home_url().

wp_weixin_follower_welcome_description

apply_filters( 'wp_weixin_follower_welcome_description', string $description, mixed $before_subscription );

Description
Filter the description of the message the user receives when following the Official Account.

Parameters
$description

(string) The description - default "Thank you for subscribing our official account!".

$before_subscription

(mixed) If numeric, the WP_Post ID of the last page the user was visiting ; if string, the URL of the last page the user was visiting - default home_url().

wp_weixin_follower_welcome_url

apply_filters( 'wp_weixin_follower_welcome_url', string $url, mixed $before_subscription );

Description
Filter the URL the user will be redirected to when interacting with the message received when following the Official Account.

Parameters
$url

(string) The URL the user will be redirected to - default home_url() if no URL was recorded before sending the templated message.

$before_subscription

(mixed) If numeric, the WP_Post ID of the last page the user was visiting ; if string, the URL of the last page the user was visiting - default home_url().

wp_weixin_follower_welcome_pic_url

apply_filters( 'wp_weixin_follower_welcome_pic_url', string $pic_url, mixed $before_subscription );

Description
Filter the URL of the picture displayed on the message the user receives when following the Official Account.

Parameters
$pic_url

(string) The URL of the picture - default WP_PLUGIN_URL . '/wp-weixin/images/default-welcome.png'.

$before_subscription

(mixed) If numeric, the WP_Post ID of the last page the user was visiting ; if string, the URL of the last page the user was visiting - default home_url().

wp_weixin_get_access_info

apply_filters( 'wp_weixin_get_access_info', array $access_info );

Description
Filter the access token and token expiry when requesting the WP_Weixin_WeChat object (wrapper of a Wechat_SDK object) if custom persistence is used - particularly useful to avoid a race condition if the access token needs to be shared between multiple platforms.

Parameters
$access_info

(array) The access information in an associative array. Value types and keys: (string) token, (int) expiry.

wp_weixin_jsapi_urls

apply_filters( 'wp_weixin_jsapi_urls', array $jsapi_urls );

Description
Filter the URLs necessary to register on the WeChat merchant account's API configuration screen - used when another plugin implements WeChat Pay integration.

Parameters
$jsapi_urls

(array) The URLs to register on the WeChat merchant account's API configuration screen.

wp_weixin_pay_callback_endpoint

apply_filters( 'wp_weixin_pay_callback_endpoint', string $endpoint );

Description
Filter the endpoint of the QR Payment URL necessary to register on the WeChat merchant account's API configuration screen - used when implementing WeChat Pay integration.

Parameters
$callback_url

(string) The endpoint of the QR Payment URL to register on the WeChat merchant account's API configuration screen (example: /my_plugin/notify).

wp_weixin_settings

apply_filter( 'wp_weixin_settings', $settings );

Description
Filter the settings used to configure the plugin. Hooked functions or methods need to be added to this filter in a plugins_loaded action hook of priority of 5 or less.

Parameters
$settings

(array) The settings used to configure the plugin.

wp_weixin_show_settings_section

apply_filters( 'wp_weixin_show_settings_section', bool $show_section, string $section_name, array $section );

Description
Filter wether to show a settings section on the WP Weixin settings page.

Parameters
$show_section

(bool) Wether to show the settings section on the WP Weixin settings page.

$section_name

(string) The name of the settings section.

$section

(array) The section's settings.

wp_weixin_show_setting

apply_filters( 'wp_weixin_show_setting', bool $show_setting, string $section_name, int $index, array $value );

Description
Filter wether to show a setting on the WP Weixin settings page.

Parameters
$show_setting

(bool) Wether to show the setting on the WP Weixin settings page.

$section_name

(string) The name of the section the setting belongs to.

$index

(int) The index of the setting in the section.

$value

(array) The setting.

wp_weixin_settings_fields

apply_filters( 'wp_weixin_settings_fields', array $settings_fields );

Description
Filter the settings fields displayed on the WP Weixin settings page.

Parameters
$include_section

(array) The settings fields displayed on the WP Weixin settings page.

wp_weixin_auth_redirect

apply_filters( 'wp_weixin_auth_redirect', mixed $redirect, bool $auth, bool $has_error );

Description
Filter the URL to redirect to when QR code authentication in classic browsers is performed.

Parameters
$redirect

(mixed) The URL to redirect to when authentication is performed, or false if no redirect. Default is home_url() in case of successful authentication.

$auth

(bool) Wether the authentication was a performed - true if successful, false if an error occurred.

$has_error

(bool) Wether an error occurred.

wp_weixin_scan_heartbeat_frequency

apply_filters( 'wp_weixin_scan_heartbeat_frequency', int $frequency );

Description
Filter the frequency of the checks when waiting for QR code scan confirmation in classic browsers.

Parameters
$frequency

(int) The frequency in milliseconds. Default 1000.

wp_weixin_qr_cleanup_frequency

apply_filters( 'wp_weixin_qr_cleanup_frequency', string $frequency );

Description
Filter the frequency to clean up expired QR code data.

Parameters
$frequency

(string) The frequency. Default 'hourly'.

wp_weixin_qr_lifetime

apply_filters( 'wp_weixin_qr_lifetime', int $lifetime );

Description
Filter the lifetime of a potentially sensitive QR code, such as WeChat authentication or WeChat account binding.

Parameters
$lifetime

(int) The lifetime in seconds. Default 600.

wp_weixin_user_wechat_info

apply_filters( 'wp_weixin_user_wechat_info', mixed $wechat_info, int $user_id );

Description
Filter the user WeChat information.

Parameters
$wechat_info

(mixed) An array of WeChat information if exist, false otherwise.

$lifetime

(int) The user ID - default 0.

wp_weixin_ms_auto_add_to_blog

apply_filters( 'wp_weixin_ms_auto_add_to_blog', bool $auto_add_to_blog, int $blog_id, int $user_id );

Description
Filter wether to automatically add the user to the visited blog on the network when authenticated with WeChat.

Parameters
$auto_add_to_blog

(bool) Wether to automatically add the user to the visited blog on the network when authenticated with WeChat - default true.

$blog_id

(int) The ID of the visited blog.

$user_id

(int) The ID of the user visiting the blog.

wp_weixin_ms_auth_blog_id

apply_filters( 'wp_weixin_ms_auth_blog_id', int $auth_blog_id );

Description
Filter the blog ID used for authentication - by default, it is assumed the domain name of the default blog is registered in WeChat backend.

Warning: to make sure WP Weixin supports multiple Official Accounts, the openIDs of bound accounts are stored using a user meta record containing the value of $auth_blog_id in its meta key ('wx_openid-' . $auth_blog_id).
If WeChat-bound WordPress users already exist (manually bound or automatically created when visiting the site with the WeChat browser), applying this filter and return an altered value of $auth_blog_id will break the relationship between the user and the recorded openID during runtime.
It is up to the developer to update the database directly, or run a one-time use code snippet like below.

Example of code snippet to run after changing the blog ID used for authentication in case WordPress users are already bound with WeChat:

global $wpdb;

$old_auth_blog_id = 1;
$new_auth_blog_id = 2;

$wpdb->query(
	$wpdb->prepare(
		"UPDATE $wpdb->usermeta SET `meta_key` = 'wx_openid-%d' WHERE `meta_key` = 'wx_openid-%d';",
		$new_auth_blog_id,
		$old_auth_blog_id
	)
);

Parameters
$auth_blog_id

(int) The ID of the blog to use when doing WeChat authentication. Default 1.

wp_weixin_ms_pay_blog_id

apply_filters( 'wp_weixin_ms_pay_blog_id', int $pay_blog_id );

Description
Filter the blog ID used to build the URLs allowed to call and receive payment notifications from the WeChat Pay API - by default, it is assumed the domain ( or subdomain ) corresponding to the ID of the the current blog is registered in WeChat backend. Useful in case several instances of WooCommerce are running on the same network, or in the case of a network connected to several Official Accounts.

Parameters
$pay_blog_id

(int) The ID of the blog used to build the QR Payment callback URL. Default get_current_blog_id().

wp_weixin_locate_template_paths

apply_filters( 'wp_weixin_locate_template_paths', array $paths, string $plugin_name );

Description
Filter the possible paths of templates included by WP Weixin and companion plugins.

Parameters
$paths

(array) The possible paths. Default (where $template_name is the template's file name):

array(
	'plugins/wp-weixin/' . $plugin_name . $template_name,
	'wp-weixin/' . $plugin_name . $template_name,
	'plugins/' . $plugin_name . $template_name,
	$plugin_name . $template_name,
	'wp-weixin/' . $template_name,
	$template_name,
);

$plugin_name

(string) The name of the plugin the template belongs to.

wp_weixin_get_user_by_openid

apply_filters( 'wp_weixin_get_user_by_openid', $user, $openid );

Description
Filter the result of a query getting a WordPress user associated with a recorded WeChat openID.

Parameters
$user

(mixed) The WP_User object if the user was found, false otherwise.

$openid

(string) The openID used to search for the user

wp_weixin_pay_notify_results

apply_filters( 'wp_weixin_pay_notify_results', (array) $results );

Description
Filter the results of handling a payment notification.

Not actually applied by WP Weixin directly itself, but only after a companion plugin has fired wp_weixin_handle_payment_notification.
See a WeChat Pay integration plugin skeleton for how to add payment notification results.

Parameters
$results

(array) An array of payment notification results. Structure of a result:

array(
	'success'      => false,    // optional - (bool) wether the transaction to handle was found ; default false
	'data'         => $data,    // required - (array) return value of WP_Weixin_Wechat::getNotify()
	'refund'       => false,    // optional - (mixed) false if no refund needed, true or an refund message for the user otherwise ; default false
	'notify_error' => false,    // optional - (mixed) false if no error, true or an error message otherwise ; if truthy and pay_handler set to true, WeChat Pay API will continue to send notifications for the transaction ; default false
	'blog_id'      => $blog_id, // required for multisite, optional otherwise - (int) the ID of the blog where the original transaction was made ; default the return value of get_current_blog_id()
	'pay_handler'  => false,    // optional - (bool) wether the result is for the callback registered in the WeChat Pay backend ; default false
	/* More custom items can safely be added to the array */
);

wp_weixin_ecommerce_description

apply_filters( 'wp_weixin_ecommerce_description', $ecommerce_description );

Description
Filter the description of the WeChat Pay Settings.

Parameters
$ecommerce_description

(string) The description of the WeChat Pay Settings (HTML).

wp_weixin_subscribe_qr_url

apply_filters( 'wp_weixin_subscribe_qr_url', $wp_weixin_subscribe_qr_url );

Description
Filter the url for the WeChat Official Account subscription QR code.

Parameters
$wp_weixin_subscribe_qr_url

(string) The url for the WeChat Official Account subscription QR code.

Templates

The following template files are selected using the locate_template() and included with load_template() functions provided by WordPress. This means they can be overloaded in the active WordPress theme. Developers may place their custom template files in the following directories under the theme's folder (in order of selection priority):

  • plugins/wp-weixin/
  • wp-weixin/
  • plugins/
  • at the root of the theme's folder

The available paths of the templates may be customised with the wp_weixin_locate_template_paths filter. The style applied to all the templates below is enqueued as 'wp-weixin-main-style'.

Templates index:

wp-weixin-subscribe

wp-weixin-subscribe.php

Description
The template of the page displaying the QR code to follow the Official Account. Used when "Force follow" is enabled in the settings.

$title

(string) The title of the screen presented to the user.

$message

(string) The message describing why the user sees this screen.

$qr_src

(string) The source of the QR code image.

wp-weixin-browser-qr

wp-weixin-browser-qr.php

Description
The template of the page displaying the QR code when the website is accessible only through the WeChat browser.

Variables
$page_qr_src

(string) The source of the QR code image.

wp-weixin-auth-form-link

wp-weixin-auth-form-link.php

Description
The template of the WeChat authentication link.

Variables
$class

(string) The class attribute of the link.

$target

(string) The target attribute of the link.

wp-weixin-auth-page

wp-weixin-auth-page.php

Description
The template of the WeChat screen displayed for QR code authentication in classic browsers.

wp-weixin-mobile-auth-check

wp-weixin-mobile-auth-check.php

Description
The template of the WeChat mobile browser screen displayed when authenticating via QR code authentication in classic browsers.

Variables
$auth_qr_data

(array) Data related to the authentication. Value types and keys: (bool) auth, (int) user_id, (array) error, (bool|string) redirect. The redirect value is not actually used for redirection by default on mobile (used after authentication on desktop).

wp-weixin-bind-form-link

wp-weixin-bind-form-link.php

Description
The template of the WeChat account binding link.

Variables
$link_text

(string) The text of the link.

$wechat_info

(mixed) An array of WeChat information if exists, false otherwise.

$class

(string) The class attribute of the link.

$target

(string) The target attribute of the link.

wp-weixin-bind-page

wp-weixin-bind-page.php

Description
The template of the WeChat screen displayed for WeChat account bindind in classic browsers.

Variables
$user_id

(int) The ID of the user to bind to a WeChat account.

$wechat_info

(mixed) An array of WeChat information if exists, false otherwise.

wp-weixin-mobile-bind-check

wp-weixin-mobile-bind-check.php

Description
The template of the WeChat mobile browser screen displayed when attempting to a WeChat account via QR code in classic browsers.

Variables
$bind_qr_data

(array) Data related to the account binding. Value types and keys: (bool) bind, (int) user_id, (array) error, (bool|string) redirect. The redirect value is always false on mobile (populated and used after account binding on desktop).

wp-weixin-public-info

wp-weixin-public-info.php

Description
The template to output the WeChat public information - notably used when calling wp_weixin_get_user_wechat_info with the $output parameter set to false.

Variables
$wechat_info

(array) The WeChat public information. Value are all of type (string), with keys: nickname, headimgurl, sex, language, city, province, country, unionid.

wp-weixin-account-form-password-notice

wp-weixin-account-form-password-notice.php

Description
The template of the notice to show under the form to change the user account password.

JavaScript

The global variable wx is already properly signed and initialised with the complete jsApiList.
To use it properly, developers must:

  • include their scripts in wp_enqueue_scripts action hook with a priority of 6 or more,
  • make sure to set wp-weixin-main-script as a dependency
  • make sure "Enabled" is checked in WP Weixin Main Settings

In addition, a provided list of listeners may be subscribed to.

JavaScript listeners index:

Example for how to subscribe to the wpWeixinShareTimelineSuccessListener listener:

window.wpWeixinShareTimelineSuccessListener( handleShareTimelineSuccess );

function handleShareTimelineSuccess( shareInfo ) {
	// do something with the data
	do_something( shareInfo );
}

wpWeixinShareTimelineSuccessListener

window.wpWeixinShareTimelineSuccessListener( callback );

Subscribing to this listener will execute the callback function after sharing the post on WeChat Moments succeeded.

Parameters passed to the callback
shareInfo

(object) The share information sent to the WeChat JS_SDK. Attributes are title, desc, link, imgUrl.

wpWeixinShareTimelineFailureListener

window.wpWeixinShareTimelineFailureListener( callback );

Subscribing to this listener will execute the callback function after sharing the post on WeChat Moments failed.

Parameters passed to the callback
shareInfo

(object) The share information sent to the WeChat JS_SDK. Attributes are title, desc, link, imgUrl.

wpWeixinShareAppMessageSuccessListener

window.wpWeixinShareAppMessageSuccessListener( callback );`

Subscribing to this listener will execute the callback function after sharing the post with WeChat "Send to chat" succeeded.

Parameters passed to the callback
shareInfo

(object) The share information sent to the WeChat JS_SDK. Attributes are title, desc, link, imgUrl.

wpWeixinShareAppMessageFailureListener

window.wpWeixinShareAppMessageFailureListener( callback );

Subscribing to this listener will execute the callback function after sharing the post with WeChat "Send to chat" failed.

Parameters passed to the callback
shareInfo

(object) The share information sent to the WeChat JS_SDK. Attributes are title, desc, link, imgUrl.

About

WordPress WeChat integration

Topics

php wordpress-plugin wordpress-development wechat

Resources

Readme

License

GPL-3.0 license
Activity

Stars

92 stars

Watchers

10 watching

Forks

38 forks
Report repository

Releases 4

WP Weixin v1.3.11 Latest
Mar 19, 2020
+ 3 releases

Packages

No packages published

Languages