The Plugin API

Contents

• Preface
  • Syntax Used In This Guide
  • Class Imports Used In This Guide
• The Plugin Interface
  • getName()
  • getDescription()
  • getHelpText() (Unused)
  • getCommandEndpoints()
  • getEventHandlers()
  • getMessageHandler()
  • enableForRoom()
  • disableForRoom()
  • Composite Default Implementation Traits
• The PluginCommandEndpoint Class
• Event Filter Strings
  • Syntax
  • Supported Fields
    • type
    • room
    • class
  • Examples

Preface

Syntax Used In This Guide

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

• async 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. Async callbacks use async instead of the function keyword, for brevity.

Class Imports Used In This Guide

A number of class names are assumed to be imported in this guide for brevity.

use Room11\Jeeves\Chat\Room\Room as ChatRoom;

The Plugin Interface

A Jeeves plugin must implement all the methods of the Room11\Jeeves\System\Plugin interface.

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. The BasePlugin implementation returns the class name.

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. BasePlugin does not implement this method.

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.

getEventHandlers() : (async(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.

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

Returns a callback that will be invoked once for every message that received. The corresponding Message object will be passed to the callback. This method may return null if the plugin does not wish to register a message handler. This method will be invoked exactly once during registration of the plugin with the bot.

async enableForRoom(ChatRoom $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.

async disableForRoom(ChatRoom $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.

The BasePlugin class

Many of the methods in the Plugin interface 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, plugins may extend the Room11\Jeeves\System\BasePlugin class which provides default "null" implementations of most methods.

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,
    (async(Command $command)) $callback,
    string $defaultCommand = null,
    string $description = null
)

• $name is a unique, descriptive name for the endpoint. It should contain only alpha-numeric characters.
• $callback will be invoked when a command mapped to the endpoint is invoked.
• $defaultCommand is the default command that will be assigned to the endpoint when the plugin is enabled for the first time in a room. If omitted or null is passed, the endpoint will not be enabled by default.
• $description is a human-readable description of what the endpoint does. If this is omitted, the plugin's description string will be used instead. In general, a plugin which only exposes a single command endpoint need not provide a description.

Event Filter Strings

Event filters can be used to capture arbitrary events received on the chat websockets. The strings are used as the keys for the map returned by getEventHandlers().

Filter Syntax

Filters are similar in appearance to application/x-www-form-urlencoded strings. They do not need to be URL-encoded, instead values that contain characters that need to be escaped can be quoted as strings using single or double quotes.

A filter is constructed from one or more conditions, separated by ampersands. All of the conditions must match for a filter to be considered to match. A condition is comprised of a field name on the left and a value for comparison on the right. The comparison value may also be a set, the behaviour of the set is defined by it's name, valid set names are field-dependent and documented below. Whitespace between symbols is tolerated.

Supported Filter Fields

type={id}, type=any({ids})

Matches the event type id, available from the {EventClass}::TYPE_ID constant and the Event#getTypeId() method.

room={id}, room=any({ids})

Matches the room ident string in the format domain-name#room-id. Available from the ChatRoom#getIdentifier()->getIdentString() method.

class={class}, class=any({classes}), class=all({classes})

Matches classes define event subtypes based on their API. Currently available classes are:

• user => UserSourcedEvent
• room => RoomSourcedEvent
• message => MessageEvent

Example Filters

• type = 1 - matches all NewMessage events
• type = 1 & room = chat.stackoverflow.com#11 - matches all NewMessage events from StackOverflow PHP chat
• room=chat.stackoverflow.com#11&class=any(user,room) - matches any message from SO PHP chat that is UserSourcedEvent or RoomSourcedEvent