CommandSync
in package
Decides whether the application command Discord already has still matches the one this build defines.
Without this, a bot that registers a command only when it is missing keeps whatever it published the first time: add a sub-command, restart, and the new one is routed in code but never offered by Discord — the handler simply cannot be reached. Re-creating the command on every boot is not the answer either, since a global command takes up to an hour to propagate and the write is rate limited.
So the two definitions are compared, and only a real difference is
published. The comparison has to be lenient about everything Discord adds on
its way back — id, application_id, version, defaults it fills in, and
key order — or every restart would look like a change.
Tags
Table of Contents
Constants
- COMMAND_FIELDS : mixed = ['name', 'description', 'type', 'options', 'con...
- The fields that actually describe a command. Anything else Discord echoes back is ignored.
- OPTION_FIELDS : mixed = ['name', 'description', 'type', 'required', 'op...
- The fields that describe one option.
Methods
- canonical() : array<string, mixed>
- Reduces a command payload to the part worth comparing: known fields only, defaults made explicit, ordering made irrelevant.
- differs() : bool
- Whether the published command differs from the one just built.
- stale() : array<int, string>
- The names Discord still has registered that this build no longer defines.
- canonicalChoices() : array<int, array{name: string, value: mixed}>
- canonicalOptions() : array<int, array<string, mixed>>
- Options are ordered — a sub-command list is shown in the order it was declared — so they are canonicalised in place rather than sorted.
- canonicalSet() : array<int, mixed>
- toArray() : array<string|int, mixed>
- Whatever DiscordPHP handed over — an array, a Collection, a Part, a `stdClass` off the wire — as a plain array.
Constants
COMMAND_FIELDS
The fields that actually describe a command. Anything else Discord echoes back is ignored.
private
mixed
COMMAND_FIELDS
= ['name', 'description', 'type', 'options', 'contexts', 'integration_types', 'default_member_permissions', 'nsfw']
OPTION_FIELDS
The fields that describe one option.
private
mixed
OPTION_FIELDS
= ['name', 'description', 'type', 'required', 'options', 'choices', 'channel_types', 'min_value', 'max_value', 'min_length', 'max_length', 'autocomplete']
Methods
canonical()
Reduces a command payload to the part worth comparing: known fields only, defaults made explicit, ordering made irrelevant.
public
static canonical(array<string, mixed> $payload[, array<int, string> $fields = self::COMMAND_FIELDS ]) : array<string, mixed>
Parameters
- $payload : array<string, mixed>
- $fields : array<int, string> = self::COMMAND_FIELDS
Return values
array<string, mixed>differs()
Whether the published command differs from the one just built.
public
static differs(array<string, mixed> $published, array<string, mixed> $built) : bool
Parameters
- $published : array<string, mixed>
-
What Discord has.
- $built : array<string, mixed>
-
What this build defines.
Return values
boolstale()
The names Discord still has registered that this build no longer defines.
public
static stale(iterable<string|int, object|array<string, mixed>> $published, array<int, string> $declared) : array<int, string>
Renaming a command is two operations, and only one of them is obvious.
Publishing /twitch leaves the /relay it replaced sitting in every
server's command list, pointing at a handler that no longer exists —
which looks like a broken bot rather than a renamed one. So what is
stale is worked out and deleted.
The caller is expected to do this only after every connector has started. A connector that failed to boot never declared its commands, and pruning against an incomplete list would delete the working commands of whichever package happened to be unlucky.
Parameters
- $published : iterable<string|int, object|array<string, mixed>>
-
What Discord has, as parts or payloads.
- $declared : array<int, string>
-
Every top-level name this build defines.
Return values
array<int, string>canonicalChoices()
private
static canonicalChoices(mixed $choices) : array<int, array{name: string, value: mixed}>
Parameters
- $choices : mixed
Return values
array<int, array{name: string, value: mixed}>canonicalOptions()
Options are ordered — a sub-command list is shown in the order it was declared — so they are canonicalised in place rather than sorted.
private
static canonicalOptions(mixed $options) : array<int, array<string, mixed>>
Parameters
- $options : mixed
Return values
array<int, array<string, mixed>>canonicalSet()
private
static canonicalSet(mixed $values) : array<int, mixed>
Parameters
- $values : mixed
Return values
array<int, mixed>toArray()
Whatever DiscordPHP handed over — an array, a Collection, a Part, a `stdClass` off the wire — as a plain array.
private
static toArray(mixed $value) : array<string|int, mixed>
Parameters
- $value : mixed