Creating a Custom Connector

Introduction

Connectors are the mechanism by which Stream logs activity that's happening in WordPress.

Connectors are really just a simple way to encapsulate the instructions Stream needs to monitor actions taken by specific WordPress components, like Posts, as well as actions by specific plugins, like Jetpack.

A Connector is comprised of six primary components:

1. Connector name/slug
2. Connector label
3. Context labels
4. Action labels
5. Action callbacks
6. Callback functions

Understanding Contexts

A Connector should be thought of as a top-level Context, and Contexts listed within our Connector as second-level Contexts.

These second-level Contexts help to further categorize actions that are happening within the Connector we are tracking.

For example, if there is a custom post type called "Books" and there is a book post called "Moby Dick" that is updated, the Stream record data would look like this:

Summary: "Moby Dick" book updated

Contexts: Posts > Books

Action: Updated

The Connector Class

Every Connector registered in Stream must be a child class that inherits from the main WP_Stream_Connector abstract class where the required arguments for Connector methods are defined.

Connector Example

<?php

class WP_Stream_Connector_My_Plugin extends WP_Stream_Connector {

	/**
	 * Connector name/slug
	 *
	 * @var string
	 */
	public static $name = 'my_plugin';

	/**
	 * The minimum version required for My Plugin
	 *
	 * @const string
	 */
	const PLUGIN_MIN_VERSION = '1.0.0';

	/**
	 * Actions registered for this connector
	 *
	 * These are actions that My Plugin has created, we will create callbacks
	 * for each of these actions.
	 *
	 * @var array
	 */
	public static $actions = array(
		'my_plugin_create_thingy',
		'my_plugin_update_thingy',
		'my_plugin_delete_thingy',
	);

	/**
	 * Check if plugin dependencies are satisfied and add an admin notice if not
	 *
	 * @return bool
	 */
	public static function is_dependency_satisfied() {
		if (
			class_exists( 'My_Plugin_Class' )
			&&
			version_compare( My_Plugin_Class::$version, self::PLUGIN_MIN_VERSION, '>=' )
		) {
			return true;
		}

		return false;
	}

	// @TODO

}