Creating a Custom Connector - xwp/stream GitHub Wiki

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. Action callbacks
4. Action labels
5. Context labels
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.

Creating a Custom Stream Connector

To log custom events from your plugin or theme using Stream, you'll need to create a custom Connector. This involves:

• Registering the Connector Class: Integrate your custom connector into Stream.
• Defining Actions and Callbacks: Specify WordPress hooks (actions) and the corresponding callback functions that will create log records.
• Setting Up Labels: Configure the labels displayed on the Stream admin screens.

Example: Stream Observer Connector

The following example demonstrates how to create a simple Stream Connector that logs visits to the Stream Settings and Alerts admin screens. While this example is more illustrative than practical, it effectively demonstrates the core concepts involved in building a custom Stream Connector.

Step 1: Register the Connector

In the main plugin file, you’ll need to register your connector class with Stream using the wp_stream_connectors filter:

<?php
/**
 * Plugin Name: Stream Observer Connector
 *
 * @package Stream_Observer
 */

namespace Stream_Observer;

/**
 * Register the Stream Observer connector.
 *
 * @param array $classes Array of connector class names.
 *
 * @return array
 */
add_filter(
	'wp_stream_connectors',
	function ( $classes ) {
		require plugin_dir_path( __FILE__ ) . '/classes/class-connector.php';

		$classes[] = new Connector();

		return $classes;
	}
);

Step 2: Define the Connector Class

Next, create the connector class that defines the actions to be logged and their corresponding callback functions.

<?php
/**
 * Stream Observer - a connector to log Stream admin screens visits.
 *
 * @package Stream_Observer
 */

namespace Stream_Observer;

class Connector extends \WP_Stream\Connector {
	/**
	 * "Visited" action slug.
	 */
	const ACTION_VISITED = 'visited';

	/**
	 * "Admin" context slug.
	 */
	const CONTEXT_ADMIN = 'admin';

	/**
	 * Connector slug.
	 *
	 * @var string
	 */
	public $name = 'stream_observer';

	/**
	 * Actions registered for this connector.
	 *
	 * These are actions (WordPress hooks) that the Stream_Observer connector
	 * will listen to. Whenever an action from this list is triggered, Stream
	 * will run a callback function defined in the connector class.
	 *
	 * The callback function names follow the format: `callback_{action_name}`.
	 *
	 * @var array
	 */
	public $actions = array(
		'current_screen',
	);

	/**
	 * Return translated connector label.
	 *
	 * @return string
	 */
	public function get_label() {
		return __( 'Stream Observer', 'stream-observer' );
	}

	/**
	 * Return translated context labels.
	 *
	 * @return array
	 */
	public function get_context_labels() {
		return array(
			self::CONTEXT_ADMIN => __( 'Admin', 'stream-observer' ),
		);
	}

	/**
	 * Return translated action labels.
	 *
	 * @return array
	 */
	public function get_action_labels() {
		return array(
			self::ACTION_VISITED => __( 'Visited', 'stream-observer' ),
		);
	}

	/**
	 * Track `current_screen` action and log Stream screens visits.
	 *
	 * @param \WP_Screen $current_screen Current `WP_Screen` object.
	 *
	 * @return void
	 */
	public function callback_current_screen( $current_screen ) {
		if ( ! ( $current_screen instanceof \WP_Screen ) ) {
			return;
		}

		// We want to log visits to the Alerts or Settings screens.
		$tracked_screens = array(
			'edit-wp_stream_alerts'          => __( 'Alerts', 'stream-observer' ),
			'stream_page_wp_stream_settings' => __( 'Settings', 'stream-observer' ),
		);

		if ( ! isset( $tracked_screens[ $current_screen->id ] ) ) {
			return;
		}

		$this->log(
			/* translators: %1$s: Stream admin screen title, e.g. "Alerts".. */
			__( 'Stream "%1$s" screen visited', 'stream-observer' ),
			// This array will be compacted and saved as Stream meta.
			array(
				'title' => $tracked_screens[ $current_screen->id ],
				'id'    => $current_screen->id,
			),
			// Stream admin screens don't use numeric IDs so we set object ID to 0.
			0,
			self::CONTEXT_ADMIN,
			self::ACTION_VISITED,
		);
	}
}

Key Components of the Connector

Actions to Listen To

The connector listens to the current_screen action, which is defined in the $actions array:

public $actions = array(
    'current_screen',
);

Logging Events

The callback function callback_current_screen triggers whenever the current_screen action is called. It logs the visit using the $this->log( ... ) method:

public function callback_current_screen( $current_screen )

This example provides a foundational understanding of how to create a custom Stream Connector. You can expand on this by adding more actions and logic to suit your plugin or theme’s needs.