Plugin Integrations API

A bonus feature of XFtoWP 1.2 is the new integrations API for developers to hook into and run forum actions on different plugin. You can take advantage of these tools to start writing your own eCommerce or membership integrations.

This guide will teach you how to use the XFtoWP Integrations API to run any supported XF user actions on common plugin actions like on product purchase, on product expiration, and even target when user’s reset their email and password.

Step 1: Create a new plugin file

You will be writing an integration into a brand new plugin where you will be able to easily access classes, functions, and other assets from the main XFtoWP plugin.

To create a new plugin navigate to /wp-content/plugins/ and create a new folder. In this guide we will use “XFWP-Integration” as the plugin folder.

Once the folder is created, you can now create a .php file with the same name as the folder. This is part of the basics of WordPress plugins.

Step 2: Add plugin header info

Now with your empty file, register the plugin to WordPress by pasting the following DocBlock to the top of the top of the file:

<?php
/**
 * Version: 1.0
 * Plugin Name: XFtoWP - Integration Name
 * Plugin URI: https://plugindomain.com
 * Description: Connect your XF site to Integration Name.
 * Author: Your name
 * Author URI: https://authordomain.com/
 * Author email: author@email.com
 */

Save your file and you should now see your new plugin in the WordPress admin > Plugins panel. Go ahead and activate it so you can immediately begin working with your new integration plugin.

Step 3: Add a new integration to XFtoWP

Now, let’s get into our XFtoWP integration. I have removed comments from the code example below but if you are an existing customer you should read the /plugins/XFWP/integration.php file and also the /plugins/XFWP-Integration plugin for a literal example.

To connect to XFtoWP’s API we have to extend the XFWP_Integration Class and plugin some basic settings about the integration.

Unfortunately, as of XFtoWP beta 2, this class has to be instantiated inside of a function that loads to the WordPress plugins_loaded hook so we can access the XFWP_Integration Class from the separate plugin.

While a minor nuisance, the actual code itself is still pretty basic:

add_action( 'plugins_loaded', 'xfwp_my_custom_integration' );

function xfwp_my_custom_integration() {

	if ( ! class_exists( 'XFWP' ) || ! class_exists( 'XFWP_Integration' ) )
		return;

	class XFWP_My_Custom_Integration extends XFWP_Integration {

		public $_id = 'my-custom-integration';
		public $label = 'Integration Name';
		public $post_types = array( 'post_type_id' );

	}

	new XFWP_My_Custom_Integration;

}

You see we created a new function named xfwp_my_custom_integration() and hook it to the plugins_loaded hook. I recommend you change this function name to match your integration.

Moving down we see:

if ( ! class_exists( 'XFWP' ) || ! class_exists( 'XFWP_Integration' ) )
		return;

This makes sure the XFtoWP plugin exists and has the new integration class, otherwise it stops the rest of the plugin from executing. You should also add an OR statement for the plugin you integration with XFtoWP.

Finally, we can see the basic Class declaration next. Again, change the class names to match your own integration plugin.

class XFWP_My_Custom_Integration extends XFWP_Integration {

	public $_id = 'my-custom-integration';
	public $label = 'Integration Name';
	public $post_types = array( 'post_type_id' );

	public function init() {
		// run custom actions here
	}

}

new XFWP_My_Custom_Integration;

It doesn’t look like much but this simple class declaration actually takes care of a lot for you.

Properties overview:

$_id = Give your integration a unique ID. This will be used for generating any lists and accessing other data about your integration.

$label = Give your integration a name!

$post_types = Enter the post type ID(s) your product or memberships are added. This will add the XFtoWP’s “User actions” meta box to the “Edit product” pages where you can connect products to forum usergroups.

Connecting to plugin actions

At this point you could stop and trust that your integration plugin will now mostly work with XFtoWP’s user actions!

As long as your plugin uses the standard WordPress users database and adds/remove users from the “Users” admin screen, users created from the WP admin should be synced to your XenForo website.

Now, we are ready to go further and start targeting actions unique to each plugin. This is where we run the magic of creating new users on purchases, removing from usergroups on expiration, etc.

Using plugin hooks and filters to run forum user actions

Inside the init() method is where you will be able to send custom logic through action hooks and change data with filters.

The hook and filter names will be unique to any given plugin, and you can name your own methods however you please from here on out.

How do you know which hooks to use? Well, first it depends if your plugin offers hooks to the action you want. Next you have to know what actions you want to run on the forum user—group promotions, send a message, etc.

But let’s not stay abstract for much longer and look at the first official integration into XFtoWP, MemberPress, and search for the hooks we need from their action hooks documentation.

If I want to register a user when a product is purchased, I can use the mepr-txn-status-complete hook to intercept every purchase and add my own custom logic.

When you have the hook names figured out you can hook them into a new method you create in the Integration class. I’ll call the new method complete() and hook it into the MemberPress hook like so:

public function init() {
	add_action( 'mepr-txn-status-complete', array( $this, 'complete' ) );
}

public function complete( $transaction ) {
	// add logic here
}

Note: There is one parameter passed through this hook that gives us information about the current transaction for use in our new method.

Congrats! You are now hooked into the MemberPress transaction complete action.

Using the XFtoWP update_user method

From here you can begin to write your own custom logic, but there is one helper method provided in the XFWP_Integration class that will be integral to creating a smooth integration.

That is the update_user() method which is the magic helper that performs all XF forum actions to any given user. With many different parameters to plug into, you can do just about anything from creating a new user, adding secondary groups, change the password, etc.

Here is how the update_user method is used to register new users:

$this->users->update_user( $wp_user_id, array(
	'action' => 'register_user',
	'username' => 'ForumUsername',
	'password' => 'password-plaintext',
	'email' => 'email@domain.com'
) );

The only required parameter here is $wp_user_id, which tells XFtoWP the associated forum account to the current WordPress user.

The actions are tied into the very same actions as created on the User actions screen, so you can run some valet functions here very quickly.

For example, when you link a new action to Product purchased in the User actions admin like so:

…these actions will be available to the product_purchase action in the update_user() method.

The advantage here is you do not necessarily need to feed message content and usergroup changes into this method, but simply refer to them as an action and execute on your plugin hooks and filters.

So, all of that to tell you that as long as you know how to hook into your plugin’s product status hooks, you can run automated forum actions as simple as the following update_user() call:

public function complete( $transaction ) {
	$this->users->update_user( $transaction->user_id, array(
		'action' => 'product_purchase'
	) );
}

Pretty neat, huh? You are not tied to only running actions here and can of course pass parameters like we did in the register_user example, but I will explain those parameters more in-depth in the next tutorial.