Application
Table of Contents
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()}.
Classes
- Stats
- Tracks bot runtime metrics — start time, last reconnect, message/event
counters — and renders them as an {@see Embed} for a `!stats` style command.
- BoosterMessageBuilder
- An opened booster pack as a Components V2 message: every card with its
rarity, foil and price, the pack's value, a picker to look at a card, and
buttons to see the pack's images or open another.
- CardMessageBuilder
- Components V2 messages about one card: the card itself — art, rules text,
today's price, its set, and buttons for everything else — and the panels
those buttons open (rulings, legality, prices, foreign names, images,
JSON).
- DeckMessageBuilder
- A preconstructed deck as a Components V2 message: its commander, the main
board grouped by card type with counts, the sideboard, a picker to look at
a card, and an Export button for a decklist that MTG Arena and most deck
sites import.
- ListMessageBuilder
- One page of search results as a Components V2 message: a heading, a
numbered list, a picker that opens an entry, and Previous/Next buttons.
- SetMessageBuilder
- A set as a Components V2 message: what it is, when it came out, how big it
is, what boosters it has, with buttons to browse its cards, open a booster
and list its decks.
- Client
- The DiscordPHP {@see \Discord\Parts\User\Client} extended so the MTG
repositories ({@see CardRepository}, {@see SetRepository},
{@see DeckRepository}) hang off the same client the rest of the bot uses.
- Booster
- Opens booster packs from a set's MTGJSON booster configuration, as
stored in the AllPrintings build's `setBooster*` tables.
- CardQuery
- A card search against the AllPrintings build's `cards` table, joined to
`sets` (for `setName`), `cardIdentifiers` and `cardLegalities` as filters
need them. One row per card face per printing, as in MTGJSON.
- Database
- A local copy of MTGJSON's AllPrintings SQLite build, kept current from the
API. MTGJSON has no query endpoint — it publishes whole files — so card and
set searches run here instead of over HTTP.
- PriceBuilder
- Turns MTGJSON's `AllPricesToday.json` into the small SQLite build
{@see PriceDatabase} reads.
- PriceDatabase
- Today's card prices, kept current the same way as the card build: a small
SQLite file ({@see PriceBuilder}) that the `prices` GitHub Actions workflow
builds daily from MTGJSON's `AllPricesToday` and publishes as an asset of
the `prices` release, beside a `prices.json` holding its version.
- Query
- Compiles a search — the same `key => value` filters the old
api.magicthegathering.io took — into SQL against the AllPrintings build.
- SetQuery
- A set search against the AllPrintings build's `sets` table.
- Suggestions
- Autocomplete answers for command options — card names, sets, booster
types, set types, keywords and formats — fast enough to run on every
keystroke inside Discord's three-second window.
- Collection
- Collection of items. Inspired by Laravel Collections. A local copy of
DiscordPHP's `Collection` so MTG code has an `MTG\Helpers`-namespaced type;
behaviour comes entirely from {@see CollectionTrait}.
- CommandSignature
- The parts of an application command that matter to a user, in one
canonical shape — so a command built in code can be compared with the one
Discord has registered, and re-registered only when it changed.
- Links
- Links from a card or set to the sites players use: Scryfall, EDHREC and
the stores in its MTGJSON purchase URLs. Pure.
- SearchCache
- Short-lived state behind a message's components — a search's filters, an
opened booster's cards — under an id short enough for a `custom_id`.
- Text
- Small pure text helpers for rendering Magic data into Discord messages.
- Endpoint
- The route table for the MTGJSON v5 API — one constant per file the API
serves under `https://mtgjson.com/api/v5/`, with `:param` placeholders
bound via {@see EndpointTrait}. Same mechanics as DiscordPHP's own
`Endpoint`, pointed at `mtgjson.com`.
- Http
- HTTP client for the MTGJSON v5 API, built the same way DiscordPHP talks to
`discord.com` (buckets, driver, retry) but pointed at
`mtgjson.com/api/v5`. The API is read-only and unauthenticated, so no token
is required. Responses are MTGJSON's `{"meta": {...}, "data": ...}`
wrapper, decoded.
- Request
- A single queued HTTP request against the MTG API. Identical in behaviour to
the DiscordPHP request it extends; it exists only so MTG transport code
depends on an MTG-owned type.
- About
- `/about` (where the data comes from, how fresh it is, how the bot is
doing), `/invite` (add the bot to a server or to your account) and `/ping`.
- Boosters
- Opening booster packs: `/booster <set> [type]`, from MTGJSON's booster
configurations — the pack layouts, sheets and odds of the real product.
- Cards
- Card lookups: `/card show|search|random|prices`, and the original
`/card_search`.
- Decks
- Preconstructed decks: `/deck show` and `/deck search`, over MTGJSON's deck
list and deck files.
- Help
- `/help` — a guide to every command, as one Components V2 message, only to
the person who asked. The guide is {@see SECTIONS}, so it is tested and
kept beside the commands it describes.
- Lookup
- Cards named in chat.
- Sets
- Sets: `/set show` and `/set search`.
- MTG
- The MTG client class — a DiscordPHP {@see MessageCommandClient} extended
with MTGJSON: an async HTTP client for the MTGJSON v5 API, a local copy of
its AllPrintings SQLite build for card and set searches, today's card
prices, and the card, set and deck repositories that read them.
- Card
- One face of one printing of a Magic: The Gathering card — MTGJSON's Card
(Set) model, plus the Card (Deck) fields when it comes from a deck.
- Deck
- A preconstructed deck — MTGJSON's Deck model, or a Deck List entry (no
cards) when it comes from {@see \MTG\Repository\DeckRepository::getDecks()}.
- ForeignData
- One entry from a {@see Card}'s `foreignData` — the card as printed in
another language. Not available for all sets.
- Identifiers
- A {@see Card}'s `identifiers` — its ids on other services. Every value is
a string, as in MTGJSON.
- LeadershipSkills
- A {@see Card}'s `leadershipSkills` — the formats it can be your
commander in.
- Legality
- One entry of a {@see Card}'s `legalities` — its status in one format.
- PurchaseUrls
- A {@see Card}'s `purchaseUrls` — links to buy it, through MTGJSON's
referral redirects.
- Ruling
- One entry from a {@see Card}'s `rulings` — an official clarification,
with the date it was issued.
- Set
- A Magic: The Gathering set — MTGJSON's Set model, without the card, token,
deck, booster and sealed product lists (search cards by `setCode`, and
open boosters with {@see \MTG\Repository\SetRepository::generateBooster()}).
- AbstractRepository
- Base class for the MTG read-only repositories: DiscordPHP's
{@see DiscordAbstractRepository} behaviour (keyed, cached collection of
Parts) backed by MTGJSON — the {@see \MTG\Http\Http} client for the small
API files, and the local {@see Database} build for cards and sets.
- CardRepository
- Card printings from MTGJSON's AllPrintings build — search with any
{@see CardQuery} filter, and fetch one by its MTGJSON `uuid` — hydrating
{@see Card} parts with their identifiers, legalities, rulings, foreign
data and purchase URLs.
- DeckRepository
- Preconstructed decks from the MTGJSON API: the deck list
(`DeckList.json`) to search, and one deck with its cards
(`decks/{fileName}.json`) to fetch, hydrating {@see Deck} parts.
- SetRepository
- Sets from MTGJSON's AllPrintings build — search them, fetch one by code,
and open booster packs from their booster configurations — hydrating
{@see Set} parts with their name translations.
Traits
- HelperTrait
- Small presentation helpers shared by {@see MTG} and its command handlers for
turning MTG API data into Discord output: a mention-safe
{@see MessageBuilder} factory and emoji lookup helpers. Pure formatting — no
API or model concerns live here.
- InteractionTrait
- What every module does with interactions: build its commands for every
place the bot can be used, read option values, answer autocomplete, and
reply after deferring — so a search that waits on the card build (or
fails) still answers.
- AbstractRepositoryTrait
- Shared implementation for every MTG repository: DiscordPHP's
`AbstractRepositoryTrait` ported so the collection is keyed and cached the
same way, but backed by {@see \MTG\Http\Http} and MTG
{@see \MTG\Http\Endpoint}s. Consumed by {@see AbstractRepository}.
- DatabaseRepositoryTrait
- `fetch()`, `fresh()` and `freshen()` for repositories answered from the
local MTGJSON build instead of an HTTP endpoint. MTGJSON serves cards and
sets only inside whole files, so there is no per-item route to call.