Action
in package
One command, declared once and registered into every chat the bot is in.
The handler receives a Context and Arguments and returns the
reply — a string, null for "say nothing", or a promise of either. It is
never handed a Message, a ChatMessage or an Interaction, which is what
keeps a single definition serviceable from platforms that agree on almost
nothing.
Every command is qualified
A command has three parts: the qualifier, which is the connector that owns it; an optional group; and the name.
twitch · channel · title
The qualifier is not decoration. A name is only free because no connector has
claimed it yet — title belongs to Twitch today and to something else the
moment a fourth network arrives — and since every connector's commands are
offered on every surface, an unqualified catalogue is one package away from
two commands answering to the same word. Qualifying makes that impossible by
construction rather than by luck.
Each surface renders the parts it has room for:
| Surface | Form |
|---|---|
| Discord slash | /twitch channel title |
| Discord prefix | !twitch channel title |
| Any other chat | !twitch title |
Discord caps a command at 25 options, which is why the group exists at all; a chat has no such cap, so it drops the group and stays short. It never drops the qualifier, and ActionRegistry refuses two actions that would flatten to the same thing.
Tags
Table of Contents
Properties
- $access : Access
- $aliases : array<string|int, mixed>
- $cooldown : int
- $description : string
- $group : string|null
- $name : string
- $only : string|null
- $qualifier : string
- $sensitive : bool
- $slash : Slash|null
- $usage : string
- $handler : callable(Context, Arguments): Array
Methods
- __construct() : mixed
- availableOn() : bool
- Whether this action is offered on `$surface` at all.
- declaresOption() : bool
- Whether this action takes an option by that name — in which case a value given for it is the action's own argument, not a request to act on some other room.
- help() : string
- A one-line help entry, in the form the asking surface would accept.
- key() : string
- How this action is keyed: qualifier and leaf name, which is also its shortest unambiguous form.
- path() : array<int, string>
- Every part, in order — what a Discord slash command is built from.
- qualified() : string
- The full form, as Discord shows it: `twitch channel title`.
- run() : string|null|PromiseInterface
- Runs the handler.
Properties
$access read-only
public
Access
$access
= Access::Everyone
$aliases read-only
public
array<string|int, mixed>
$aliases
= []
$cooldown read-only
public
int
$cooldown
= 0
$description read-only
public
string
$description
= ''
$group read-only
public
string|null
$group
= null
$name read-only
public
string
$name
$only read-only
public
string|null
$only
= null
$qualifier read-only
public
string
$qualifier
$sensitive read-only
public
bool
$sensitive
= false
$slash read-only
public
Slash|null
$slash
= null
$usage read-only
public
string
$usage
= ''
$handler read-only
private
callable(Context, Arguments): Array
$handler
Methods
__construct()
public
__construct(string $qualifier, string $name, callable(Context, Arguments): Array $handler[, string $description = '' ][, string $usage = '' ][, Access $access = Access::Everyone ][, string|null $group = null ][, array<int, string> $aliases = [] ][, int $cooldown = 0 ][, string|null $only = null ][, bool $sensitive = false ][, Slash|null $slash = null ]) : mixed
Parameters
- $qualifier : string
-
The owning connector's name, or
bridgefor the core's own. - $name : string
-
The leaf name, unique within the qualifier.
- $handler : callable(Context, Arguments): Array
- $description : string = ''
- $usage : string = ''
- $access : Access = Access::Everyone
- $group : string|null = null
-
Groups it under a slash sub-command group, and in
help. - $aliases : array<int, string> = []
-
Alternative leaf names, within the same qualifier.
- $cooldown : int = 0
- $only : string|null = null
-
Restrict to one surface by name;
nullfor every surface. - $sensitive : bool = false
-
Whether the reply may contain a secret.
- $slash : Slash|null = null
-
Opt in to a Discord slash command.
availableOn()
Whether this action is offered on `$surface` at all.
public
availableOn(Surface $surface) : bool
Parameters
- $surface : Surface
Return values
booldeclaresOption()
Whether this action takes an option by that name — in which case a value given for it is the action's own argument, not a request to act on some other room.
public
declaresOption(string $name) : bool
Parameters
- $name : string
Return values
boolhelp()
A one-line help entry, in the form the asking surface would accept.
public
help([string $prefix = '!' ][, bool $full = false ]) : string
Parameters
- $prefix : string = '!'
-
What that surface puts in front of a command.
- $full : bool = false
-
Whether to include the group — true for Discord, false for a chat, which drops it.
Return values
stringkey()
How this action is keyed: qualifier and leaf name, which is also its shortest unambiguous form.
public
key() : string
Return values
stringpath()
Every part, in order — what a Discord slash command is built from.
public
path() : array<int, string>
Return values
array<int, string>qualified()
The full form, as Discord shows it: `twitch channel title`.
public
qualified() : string
Return values
stringrun()
Runs the handler.
public
run(Context $context, Arguments $arguments) : string|null|PromiseInterface
Permission is not checked here — the adapters do that, because each one has to report a refusal in its own idiom, and because a platform's own command client may want to make that decision itself.