The Plugin API

A Jeeves plugin must implement all the methods of the Room11\Jeeves\Chat\Plugin interface. Many of these methods are often not required - for example, a plugin which only processes commands does not need to register an event handler or a general message handler. To help keep code tidy in these cases, a sent of traits with default "null" implementations are provided.

Syntax Used In This Guide

Some augmentations to valid PHP syntax are used in this guide.

• async function is used to indicate that the return value of a function may be either a \Generator (which will be resolved as a co-routine) or an \Amp\Promise (which will be awaited to ensure the task that it represents is completed). Any other return value will be ignored.
• Callback signatures are indicated using a closure signature enclosed in parenthesis.

Plugin Interface Methods

getName() : string

Returns a unique (case-insensitive) name for the plugin. This may be called multiple time during the lifetime of the bot and should consistently return the same string.

getDescription() : string

Returns a human-readable description of what the plugin does. This may be called multiple time during the lifetime of the bot and should consistently return the same string.

getHelpText(array $args): string

This is currently unused and will never be called by the bot.

getCommandEndpoints() : PluginCommandEndpoint[]

Returns an array of PluginCommandEndpoint objects which describe the command endpoints exposed by this object. This method will be invoked exactly once during registration of the plugin with the bot. A default implementation is provided by Room11\Jeeves\Chat\Plugin\Traits\NoCommands.

getEventHandlers() : (async function(Event $event))[]

Returns a map of callbacks. The keys are event filter strings. When a websocket event matching the filter string is received, the callback will be invoked and the event will be passed to the first argument. This method will be invoked exactly once during registration of the plugin with the bot. A default implementation is provided by Room11\Jeeves\Chat\Plugin\Traits\NoEventHandlers.

getMessageHandler() : ?(async function(Message $message))

Returns a callback that will be invoked once for every message that received. This method will be invoked exactly once during registration of the plugin with the bot. The corresponding Message object will be passed to the callback. A default implementation is provided by Room11\Jeeves\Chat\Plugin\Traits\NoMessageHandler.

async enableForRoom(\Room11\Jeeves\Chat\Room\Room $room, bool $persist)

Invoked when the plugin is enabled in a room. This occurs both when the plugin is explicitly enabled in a chat room via the !!plugin enable built-in command, and when the bot joins the room (if the plugin is enabled there). When a plugin has been explicitly enabled via a user interaction, the $persist argument will be true, indicating that the action will be remembered by the bot and that the plugin should initialise any persistent data that is required for proper operation in the target room. A default implementation is provided by Room11\Jeeves\Chat\Plugin\Traits\NoEnable.

async disableForRoom(\Room11\Jeeves\Chat\Room\Room $room, bool $persist)

Invoked when the plugin is disabled in a room. This occurs both when the plugin is explicitly disabled in a chat room via the !!plugin disable built-in command, and when the bot leaves the room (if the plugin is enabled there). When a plugin has been explicitly disabled via a user interaction, the $persist argument will be true, indicating that the action will be remembered by the bot and that the plugin should clean up any persistent data that does not need to be kept while the plugin is inactive in the target room. A default implementation is provided by Room11\Jeeves\Chat\Plugin\Traits\NoDisable.

The PluginCommandEndpoint Class

This is used to describe a command endpoint that is exposed by a plugin. In general, plugins will only need to construct these during execution of the getCommandEndpoints() method. The constructor signature is described below.

public function __construct(string $name, callable $callback, $defaultCommand = null, $description = null)