Test Kitchen/SDK/PHP SDK

This page provides a guide to using the PHP Test Kitchen SDK for instrument and experiment creators.

Quickstart

Setup

To set up a local development environment for writing instrument code, follow the setup guide for MediaWiki and Test Kitchen. For more context and tooling recommendations, see the introduction to Test Kitchen development.

Send an interaction event

An interaction event is meant to represent a basic interaction with some target or some event occurring. For example, a user hovers over a UI element or an app notifies the server of its current state.

Here's an example of an instrument that uses PHP SDK to submit an event when a user hovers over an interwiki link.

$instrument = MediaWikiServices::getInstance()
    ->getService( 'TestKitchen.InstrumentManager' )
    ->getInstrument( 'my-machine-readable-instrument-name' );

$instrument->send( 'hover', [
    'action_source' => 'value for action source',
	'action_context' => 'value for action context'
] );

The resulting event:

includes the specified value of action
includes optional interaction data you have provided in interactionData. This data must validate against the specified schema (see the interaction data fields supported by the base schema for web)
is published to the event stream you defined while registering the instrument in Test Kitchen UI
is validated against the specified schema (the one defined in the stream above)

Implementation

The PHP SDK is provided by the the TestKitchen extension.

The PHP SDK does not support sampling by pageview ID or session ID because they are not known to the server (i.e., the PHP layer of MediaWiki). Sampling support can be added if and when there is a use case for it and an appropriate sampling unit defined.

Reference

Instruments

`InstrumentManager#getInstrument`

Gets the instance of an instrument that is registered in Test Kitchen UI

Parameters:

instrumentName (string): Machine-readable name of the instrument

`Instrument#send`

Sends an event to the stream that is configured within the current instrument, and it will be validated against the corresponding schema

Parameters:

action (string): Name of the interaction. For example, click
(optional) interactionData (array): Additional event data. This data must validate against the specified schema. For example, see the interaction data fields supported by the base schema for web.

`Instrument#setSchema`

Sets the ID of the schema to validate analytics events sent with

Parameters:

schemaID (string): schemaID

Experiments

`ExperimentManager#getExperiment`

Gets the instance of an experiment that is registered in Test Kitchen UI

Parameters:

experimentName (string): Machine-readable name of the experiment

`Experiment#send`

Sends an event to the stream that is configured within the current instrument, and it will be validated against the corresponding schema

Parameters:

action (string): Name of the interaction. For example, click
(optional) interactionData (array): Additional event data. This data must validate against the specified schema. For example, see the interaction data fields supported by the base schema for web.
(optional) contextualAttributes (array): Additional per-event contextual attributes. These contextual attributes will be added to the ones that are defined in the stream associated with this instrument

`Experiment#sendExposure`

Sends an exposure event to the stream that is configured within the current experiment

`Experiment#getAssignedGroup`

Gets the group the current user was assigned by the Experiment Enrollment Sampling Authority (EESA) when they were enrolled in this experiment.

`Experiment#isAssignedGroup`

Gets whether the assigned group for the current user in this experiment is one of the given groups

Parameters:

groups (string...): Name of the groups you want to check

`Experiment#setSchema`

Sets the ID of the schema to validate analytics events sent with

Parameters:

schemaID (string): schemaID