DiscordPHP-MTG Documentation

Cards
in package

Application

implements Module uses InteractionTrait

FinalYes

Card lookups: `/card show|search|random|prices`, and the original `/card_search`.

A card answers as a Components V2 view (see CardMessageBuilder) with buttons for its rulings, legality, prices, foreign names, image and JSON, a picker for its other printings, and links to Scryfall, EDHREC and stores. A search answers with pages of cards to open; an opened card keeps a way back to its page. Card and set options autocomplete.

Every card: component is routed by one listener. Buttons that only need a uuid keep working after a restart; a search's pages expire with the search cache.

Interfaces

Module: A self-contained bot feature, as in Tutelar: it declares its own application commands ({@see commands()}, which the client registers or updates), listens for them, and routes clicks on the components of the messages it sends, from {@see boot()}.

Constants

ORDERS : array<string, string> = ['Name' => 'name', 'Mana value' => 'manaValue',...: Sort orders `/card search` offers: label → `orderBy`.
RARITIES : array<string|int, string> = ['common', 'uncommon', 'rare', 'mythic', 'speci...: Rarities `/card search` and `/card random` offer.

Methods

boot() : void: Registers commands and listeners. Called once, after the gateway and the application are ready.
commands() : array<string|int, CommandBuilder>: The application commands the module answers, as they should be registered. The client creates missing ones and updates changed ones.
describe() : string: A search's title, from its options: `type:Elf · set:KTK`.
find() : PromiseInterface<string|int, ?Card>: Finds a card by exact name, then by part of its name, optionally in one set.
name() : string: Stable short name, for logs.
page() : PromiseInterface<string|int, MessageBuilder>: A page of a search.
setFilter() : array<string|int, mixed>: The filter for a set option: its code when it is one (autocomplete gives codes), otherwise part of a set name.
view() : PromiseInterface<string|int, MessageBuilder>: A card view, with its printings and the way back to how it was reached.
answer() : PromiseInterface: Answers a component click with a new message, or by replacing the clicked message, logging what fails.
choices() : array<string|int, array{name: string, value: string}>: Autocomplete choices from `value => label` (or a list of values).
command() : CommandBuilder: A chat command usable in servers, the bot's DMs and group DMs, from a server install or a user install.
failure() : MessageBuilder: The message for a failure.
hidden() : Option: The `hidden` option every command takes: reply only to the caller.
option() : Option: A command option.
reply() : PromiseInterface: Defers the reply, then answers with what `$work` resolves to. A failure answers too: a bad search is the caller's to fix, anything else is logged.
subcommand() : Option: A sub-command with its options.
typed() : array<string, mixed>: The values typed so far into the command being autocompleted, from inside its sub-command.
values() : array<string, mixed>: Option values by name.
card() : PromiseInterface<string|int, Card>: A card by uuid.
component() : void: Routes a click on a card component.
definition() : CommandBuilder: `/card` and its sub-commands.
filters() : array<string|int, mixed>: Search filters from command options.
flip() : PromiseInterface<string|int, MessageBuilder>: The card's next face (the other side of a double-faced card, or the next part of a split or meld card).
legacy() : PromiseInterface: `/card_search`, as it always worked: the best match for the old API's filters, privately.
legacyDefinition() : CommandBuilder: `/card_search`, the bot's original command, kept for servers that use it.
navigation() : array<string|int, Button>: The buttons back to how a card was reached.
prices() : PromiseInterface: `/card prices`: today's prices for a card.
random() : PromiseInterface: `/card random`: a random card, optionally within filters, with a button for another.
roll() : PromiseInterface<string|int, MessageBuilder>: A random card within a search's filters.
search() : PromiseInterface: `/card search`: pages of matching cards, one row per card.
show() : PromiseInterface: `/card show`: one card, by name, optionally from one set.
suggest() : array<string|int, mixed>: Autocomplete for every `/card` sub-command.
withCurrent() : array<string|int, array<string|int, mixed>>: The printings for the picker, with the shown one among the 25 offered.

ORDERS

Sort orders `/card search` offers: label → `orderBy`.


    public
        array<string, string>
    ORDERS
    = ['Name' => 'name', 'Mana value' => 'manaValue', 'Newest' => '-releaseDate', 'Oldest' => 'releaseDate', 'Popularity (EDHREC)' => 'edhrecRank']

RARITIES

Rarities `/card search` and `/card random` offer.


    public
        array<string|int, string>
    RARITIES
    = ['common', 'uncommon', 'rare', 'mythic', 'special', 'bonus']

boot()

Registers commands and listeners. Called once, after the gateway and the application are ready.


    public
                    boot(MTG $mtg) : void

Parameters

$mtg : MTG

commands()

The application commands the module answers, as they should be registered. The client creates missing ones and updates changed ones.


    public
                    commands(MTG $mtg) : array<string|int, CommandBuilder>

Parameters

$mtg : MTG

Return values

array<string|int, CommandBuilder>

describe()

A search's title, from its options: `type:Elf · set:KTK`.


    public
            static        describe(array<string|int, mixed> $args) : string

Parameters

$args : array<string|int, mixed>

Return values

string

find()

Finds a card by exact name, then by part of its name, optionally in one set.


    public
            static        find(MTG $mtg, string $name[, string|null $set = null ]) : PromiseInterface<string|int, ?Card>

Parameters

$mtg : MTG
$name : string
$set : string|null = null

Return values

PromiseInterface<string|int, ?Card>

name()

Stable short name, for logs.


    public
                    name() : string

Return values

string

page()

A page of a search.


    public
            static        page(MTG $mtg, string $search, int $page) : PromiseInterface<string|int, MessageBuilder>

Parameters

$mtg : MTG
$search : string
$page : int

Return values

PromiseInterface<string|int, MessageBuilder>

setFilter()

The filter for a set option: its code when it is one (autocomplete gives codes), otherwise part of a set name.


    public
            static        setFilter(MTG $mtg, string|null $set) : array<string|int, mixed>

Parameters

$mtg : MTG
$set : string|null

Return values

array<string|int, mixed>

view()

A card view, with its printings and the way back to how it was reached.


    public
            static        view(MTG $mtg, Card $card[, string $context = '' ]) : PromiseInterface<string|int, MessageBuilder>

Parameters

$mtg : MTG
$card : Card
$context : string = '': page.<search>.<n>, random.<search> or ''.

Return values

PromiseInterface<string|int, MessageBuilder>

answer()

Answers a component click with a new message, or by replacing the clicked message, logging what fails.


    protected
            static        answer(MTG $mtg, Interaction $interaction, callable $work[, bool $update = false ]) : PromiseInterface

Parameters

$mtg : MTG
$interaction : Interaction
$work : callable: Returns a MessageBuilder or a promise of one.
$update : bool = false: Replace the clicked message instead of answering with a new, hidden one.

Return values

PromiseInterface

choices()

Autocomplete choices from `value => label` (or a list of values).


    protected
            static        choices(array<string|int, mixed> $choices) : array<string|int, array{name: string, value: string}>

Parameters

$choices : array<string|int, mixed>

Return values

array<string|int, array{name: string, value: string}>

command()

A chat command usable in servers, the bot's DMs and group DMs, from a server install or a user install.


    protected
            static        command(string $name, string $description) : CommandBuilder

Parameters

$name : string
$description : string

Return values

CommandBuilder

failure()

The message for a failure.


    protected
            static        failure(MTG $mtg, Throwable $e) : MessageBuilder

Parameters

$mtg : MTG
$e : Throwable

Return values

MessageBuilder

hidden()

The `hidden` option every command takes: reply only to the caller.


    protected
            static        hidden(MTG $mtg) : Option

Parameters

$mtg : MTG

Return values

Option

option()

A command option.


    protected
            static        option(MTG $mtg, int $type, string $name, string $description[, bool $required = false ][, bool $autocomplete = false ]) : Option

Parameters

$mtg : MTG
$type : int: An Option type constant.
$name : string
$description : string
$required : bool = false
$autocomplete : bool = false

Return values

Option

reply()

Defers the reply, then answers with what `$work` resolves to. A failure answers too: a bad search is the caller's to fix, anything else is logged.


    protected
            static        reply(MTG $mtg, Interaction $interaction, bool $hidden, callable $work) : PromiseInterface

Parameters

$mtg : MTG
$interaction : Interaction
$hidden : bool: Whether only the caller sees the answer.
$work : callable: Returns a MessageBuilder or a promise of one.

Return values

PromiseInterface

subcommand()

A sub-command with its options.


    protected
            static        subcommand(MTG $mtg, string $name, string $description, Option ...$options) : Option

Parameters

$mtg : MTG
$name : string
$description : string
$options : Option

Return values

Option

typed()

The values typed so far into the command being autocompleted, from inside its sub-command.


    protected
            static        typed(Interaction $interaction) : array<string, mixed>

Parameters

$interaction : Interaction

Return values

array<string, mixed>

values()

Option values by name.


    protected
            static        values(iterable<string|int, mixed> $options) : array<string, mixed>

Parameters

$options : iterable<string|int, mixed>: The options a command handler is given.

Return values

array<string, mixed>

card()

A card by uuid.


    private
            static        card(MTG $mtg, string $uuid) : PromiseInterface<string|int, Card>

Parameters

$mtg : MTG
$uuid : string

Return values

PromiseInterface<string|int, Card>

component()

Routes a click on a card component.


    private
                    component(MTG $mtg, Interaction $interaction, array<string|int, string> $parts) : void

Parameters

$mtg : MTG
$interaction : Interaction
$parts : array<string|int, string>: The custom id, split on :.

definition()

`/card` and its sub-commands.


    private
                    definition(MTG $mtg) : CommandBuilder

Parameters

$mtg : MTG

Return values

CommandBuilder

filters()

Search filters from command options.


    private
            static        filters(MTG $mtg, array<string|int, mixed> $args) : array<string|int, mixed>

Parameters

$mtg : MTG
$args : array<string|int, mixed>

Return values

array<string|int, mixed>

flip()

The card's next face (the other side of a double-faced card, or the next part of a split or meld card).


    private
            static        flip(MTG $mtg, string $uuid, string $context) : PromiseInterface<string|int, MessageBuilder>

Parameters

$mtg : MTG
$uuid : string
$context : string

Return values

PromiseInterface<string|int, MessageBuilder>

legacy()

`/card_search`, as it always worked: the best match for the old API's filters, privately.


    private
                    legacy(MTG $mtg, Interaction $interaction, array<string|int, mixed> $args) : PromiseInterface

Parameters

$mtg : MTG
$interaction : Interaction
$args : array<string|int, mixed>

Return values

PromiseInterface

legacyDefinition()

`/card_search`, the bot's original command, kept for servers that use it.


    private
                    legacyDefinition(MTG $mtg) : CommandBuilder

Parameters

$mtg : MTG

Return values

CommandBuilder

navigation()

The buttons back to how a card was reached.


    private
            static        navigation(string $context) : array<string|int, Button>

Parameters

$context : string

Return values

array<string|int, Button>

prices()

`/card prices`: today's prices for a card.


    private
                    prices(MTG $mtg, Interaction $interaction, array<string|int, mixed> $args) : PromiseInterface

Parameters

$mtg : MTG
$interaction : Interaction
$args : array<string|int, mixed>

Return values

PromiseInterface

random()

`/card random`: a random card, optionally within filters, with a button for another.


    private
                    random(MTG $mtg, Interaction $interaction, array<string|int, mixed> $args) : PromiseInterface

Parameters

$mtg : MTG
$interaction : Interaction
$args : array<string|int, mixed>

Return values

PromiseInterface

roll()

A random card within a search's filters.


    private
            static        roll(MTG $mtg, string $search) : PromiseInterface<string|int, MessageBuilder>

Parameters

$mtg : MTG
$search : string

Return values

PromiseInterface<string|int, MessageBuilder>

search()

`/card search`: pages of matching cards, one row per card.


    private
                    search(MTG $mtg, Interaction $interaction, array<string|int, mixed> $args) : PromiseInterface

Parameters

$mtg : MTG
$interaction : Interaction
$args : array<string|int, mixed>

Return values

PromiseInterface

show()

`/card show`: one card, by name, optionally from one set.


    private
                    show(MTG $mtg, Interaction $interaction, array<string|int, mixed> $args) : PromiseInterface

Parameters

$mtg : MTG
$interaction : Interaction
$args : array<string|int, mixed>

Return values

PromiseInterface

suggest()

Autocomplete for every `/card` sub-command.


    private
                    suggest(MTG $mtg, Interaction $interaction, Option|null $option) : array<string|int, mixed>

Parameters

$mtg : MTG
$interaction : Interaction
$option : Option|null: The focused option.

Return values

array<string|int, mixed>

withCurrent()

The printings for the picker, with the shown one among the 25 offered.


    private
            static        withCurrent(Card $card, array<string|int, array<string|int, mixed>> $printings) : array<string|int, array<string|int, mixed>>

Parameters

$card : Card
$printings : array<string|int, array<string|int, mixed>>

Return values

array<string|int, array<string|int, mixed>>

Cards in package Application implements Module uses InteractionTrait

Tags

Table of Contents

Interfaces

Constants

Methods

Constants

ORDERS

RARITIES

Methods

boot()

Parameters

Tags

commands()

Parameters

Tags

Return values

describe()

Parameters

Return values

find()

Parameters

Return values

name()

Tags

Return values

page()

Parameters

Return values

setFilter()

Parameters

Return values

view()

Parameters

Return values

answer()

Parameters

Return values

choices()

Parameters

Return values

command()

Parameters

Return values

failure()

Parameters

Return values

hidden()

Parameters

Return values

option()

Parameters

Return values

reply()

Parameters

Return values

subcommand()

Parameters

Return values

typed()

Parameters

Return values

values()

Parameters

Return values

card()

Parameters

Return values

component()

Parameters

definition()

Parameters

Return values

filters()

Parameters

Return values

flip()

Parameters

Return values

legacy()

Cards
in package

Application

implements Module uses InteractionTrait