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';

	/**
	 * Actions registered for this connector.
	 *
	 * These are actions that My Plugin has created, we are defining them here to
	 * tell Stream to run a callback each time this action is fired so we can
	 * log information about what happened.
	 *
	 * @var array
	 */
	public static $actions = array(
		'my_plugin_create_thingy',
		'my_plugin_update_thingy',
		'my_plugin_create_something',
		'my_plugin_update_something',
	);

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

	/**
	 * Display an admin notice if plugin dependencies are not satisfied.
	 *
	 * If My Plugin does not have the minimum required version number specified
	 * in the constant above, then Stream will display an admin notice for us.
	 *
	 * @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;
	}

	/**
	 * Return translated connector label
	 *
	 * @return string
	 */
	public static function get_label() {
		return __( 'My Plugin', 'my-plugin-text-domain' );
	}

	/**
	 * Return translated context labels
	 *
	 * @return array
	 */
	public static function get_context_labels() {
		return array(
			'thingy'    => __( 'Thingy', 'my-plugin-text-domain' ),
			'something' => __( 'Something', 'my-plugin-text-domain' ),
		);
	}

	/**
	 * Return translated action labels
	 *
	 * @return array
	 */
	public static function get_action_labels() {
		return array(
			'created' => __( 'Created', 'stream' ),
			'updated' => __( 'Updated', 'stream' ),
		);
	}

	/**
	 * Track create and update actions on Thingies
	 *
	 * @param array $thingy
	 * @param bool  $is_new
	 */
	public static function callback_my_plugin_create_thingy( $thingy, $is_new ) {
		self::log(
			sprintf(
				__( '"%1$s" thingy %2$s', 'my-plugin-text-domain' ),
				$thingy['title'],
				$is_new ? __( 'created', 'stream' ) : __( 'updated', 'stream' )
			),
			array(
				'action' => $is_new,
				'id'     => $thingy['id'],
				'title'  => $thingy['title'],
			),
			$thingy['id'],
			'thingy', // Context
			$is_new ? 'created' : 'updated' // Action
		);
	}

}