Context
in package
Everything an action knows about the invocation it is servicing: who asked, from where, what they are allowed to do, and — the interesting part — which room on which network the action should act upon.
That last one is the whole reason this object exists. In a platform's own chat the target is obvious: the room the command was typed in. On Discord there is no such thing, so the target is whatever that Discord channel is bridged to, which means one command does the same thing in both places without either handler knowing how the other one resolved it.
With more than one connector installed that resolution needs a connector to
resolve against, and the command's own qualifier supplies it: twitch title acts on the Twitch room this channel is bridged to, even when the same
channel is also bridged to a Telegram group.
Tags
Table of Contents
Properties
- $access : Access
- $bot : Bot
- $connector : string|null
- $invokerId : string
- $invokerName : string
- $isPublic : bool
- $message : object|null
- $surface : Surface
- $target : string|null
- $targetId : string|null
Methods
- __construct() : mixed
- channelId() : string|null
- The Discord channel this was invoked in, or `null` when it came from somewhere that is not Discord.
- discordAccess() : Access
- Resolves a Discord permission rung.
- guildId() : string|null
- The Discord server this was invoked in, or `null` in a DM or from another network's chat.
- isOwner() : bool
- Whether the invoker is the bot operator.
- ladder() : Access
- Resolves a rung on the one permission ladder.
- requireGuild() : string
- The guild, or a thrown explanation.
- requireRoom() : string
- The room as it is stored, for anything that needs the name rather than an internal id.
- requireTarget() : string
- The id to act on — the platform's own where it differs, otherwise the stored form — or a thrown explanation.
- withAccess() : self
- A copy on a different rung — for acting somewhere rank is held differently.
- withConnector() : self
- A copy acting on a different connector.
- withTarget() : self
- A copy pointed at a different room.
Properties
$access read-only
public
Access
$access
$bot read-only
public
Bot
$bot
$connector read-only
public
string|null
$connector
= null
$invokerId read-only
public
string
$invokerId
$invokerName read-only
public
string
$invokerName
$isPublic read-only
public
bool
$isPublic
= true
$message read-only
public
object|null
$message
= null
$surface read-only
public
Surface
$surface
$target read-only
public
string|null
$target
= null
$targetId read-only
public
string|null
$targetId
= null
Methods
__construct()
public
__construct(Bot $bot, Surface $surface, Access $access, string $invokerName, string $invokerId[, string|null $connector = null ][, string|null $target = null ][, string|null $targetId = null ][, bool $isPublic = true ][, object|null $message = null ]) : mixed
Parameters
- $bot : Bot
- $surface : Surface
-
The chat this was invoked from.
- $access : Access
-
What the invoker may do, on the one ladder.
- $invokerName : string
-
Display name, for addressing a reply.
- $invokerId : string
-
Platform user id.
- $connector : string|null = null
-
Which connector the action acts on.
- $target : string|null = null
-
The room, as Links stores it.
- $targetId : string|null = null
-
The platform's internal id, when it differs from the stored form.
- $isPublic : bool = true
-
Whether the reply lands somewhere many people read.
- $message : object|null = null
-
The originating message, for an adapter that needs it.
channelId()
The Discord channel this was invoked in, or `null` when it came from somewhere that is not Discord.
public
channelId() : string|null
Checked by type rather than read off whatever the adapter passed: a
Twitch or Telegram message has a channel of its own, and mistaking one
for a Discord channel id would bridge the wrong thing.
Return values
string|nulldiscordAccess()
Resolves a Discord permission rung.
public
static discordAccess(bool $isGuildOwner, bool $isAdmin, bool $isModerator, bool $isOwner) : Access
Guild owners and Administrators are treated as the top rung below the bot operator, because on Discord that is the closest equivalent: they are the people whose server it is. Manage Messages maps to moderator.
Parameters
- $isGuildOwner : bool
- $isAdmin : bool
- $isModerator : bool
- $isOwner : bool
Return values
AccessguildId()
The Discord server this was invoked in, or `null` in a DM or from another network's chat.
public
guildId() : string|null
Read off whatever the adapter passed — a Message and an Interaction
both carry it under the same name — so an action does not have to know
which one it got.
Return values
string|nullisOwner()
Whether the invoker is the bot operator.
public
isOwner() : bool
Return values
boolladder()
Resolves a rung on the one permission ladder.
public
static ladder(bool $isOwner, bool $isOwnerOfRoom, bool $isModerator) : Access
Static and free of any platform's part types so the ladder can be tested directly; an adapter passes the booleans it reads off whatever its own network calls these things.
Parameters
- $isOwner : bool
- $isOwnerOfRoom : bool
- $isModerator : bool
Return values
AccessrequireGuild()
The guild, or a thrown explanation.
public
requireGuild() : string
Configuring a bridge decides which Discord channel gets copied into a public chat, so it is not something that can be done from a DM.
Tags
Return values
stringrequireRoom()
The room as it is stored, for anything that needs the name rather than an internal id.
public
requireRoom() : string
Tags
Return values
stringrequireTarget()
The id to act on — the platform's own where it differs, otherwise the stored form — or a thrown explanation.
public
requireTarget() : string
Actions that change something call this rather than testing for null themselves, so "this channel isn't bridged yet" is worded once instead of thirty times.
Tags
Return values
stringwithAccess()
A copy on a different rung — for acting somewhere rank is held differently.
public
withAccess(Access $access) : self
Parameters
- $access : Access
Return values
selfwithConnector()
A copy acting on a different connector.
public
withConnector(string|null $connector) : self
Parameters
- $connector : string|null
Return values
selfwithTarget()
A copy pointed at a different room.
public
withTarget(string|null $target[, string|null $targetId = null ]) : self
Parameters
- $target : string|null
- $targetId : string|null = null