DiscordPHP-MTG Documentation

PriceDatabase extends Database
in package

Application

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.

Prices come from MTGJSON's partners — TCGplayer, Card Kingdom, Cardmarket, Mana Pool and (for MTGO) Cardhoarder — and are one day old at most.

Constants

DEFAULT_REFRESH_INTERVAL : int = 86400: Seconds between `Meta.json` checks by default: MTGJSON rebuilds daily.
DEFAULT_SOURCE : string = 'https://github.com/Valgorithms/DiscordPHP-MTG/...: Where the `prices` workflow publishes the build.
FILE : string = 'prices.sqlite': The file name of the installed build.
INDEXES : array<string|int, string> = []: The build is keyed by uuid already.
JSON_COLUMNS : array<string, array<string|int, string>> = ['cards' => ['leadershipSkills', 'relatedCards'...: Columns the SQL build stores as JSON text, by table.
LIST_COLUMNS : array<string, array<string|int, string>> = ['cards' => ['artistIds', 'attractionLights', '...: Columns the SQL build stores as `", "`-joined lists, by table.

Properties

$browser : Browser
$columns : array<string, array<string, string>>: Declared column types, by table, read lazily with `PRAGMA table_info`.
$date : string|null: The date (`meta.date`) of the open build.
$http : Http
$logger : LoggerInterface
$loop : LoopInterface
$opening : PromiseInterface|null: The pending first install, shared by every caller of {@see ready()}.
$path : string
$pdo : PDO|null: The open read-only connection, or null while closed.
$priceColumns : array<string, array{medium: string, provider: string, kind: string, finish: string, currency: ?string}>|null: What each price column is: column → medium, provider, kind, finish, currency.
$refreshing : PromiseInterface|null: The pending refresh, shared by every caller of {@see refresh()}.
$refreshInterval : int
$source : string: The gzipped build's URL; `prices.json` is read from beside it.
$timer : TimerInterface|null: The periodic refresh timer.
$version : string|null: The version (`meta.version`) of the open build.

Methods

__construct() : mixed
close() : void: Closes the connection and stops the refresh timer. The next query reopens it.
decode() : array<string|int, mixed>: Decodes a row of `$table` into MTGJSON's JSON shape: list and JSON columns become arrays, `BOOLEAN` columns become `bool`, and null or empty scalars are dropped.
getColumns() : array<string, string>: The columns of a table in the open build, with their declared types.
getDate() : string|null: The date (`meta.date`) of the open build, e.g. `2026-10-03`.
getPath() : string: Where the build is kept.
getVersion() : string|null: The version (`meta.version`) of the open build, e.g. `5.3.0+20261003`.
isOpen() : bool: Whether a build is open.
prices() : array<string, array<string|int, mixed>>: Today's prices for some cards, nested as MTGJSON nests them but with a single price per point: `medium → provider → {currency, retail|buylist → finish → price}`. Cards without a price are left out; nothing is returned while the build is not open.
query() : PromiseInterface<string|int, array<string|int, array<string|int, mixed>>>: Runs a read query against the build, opening (or downloading) it first.
ready() : PromiseInterface<string|int, PDO>: Opens the build, downloading it first if there is none on disk, and starts the refresh timer.
refresh() : PromiseInterface<string|int, bool>: Checks `Meta.json` and installs MTGJSON's current build if it is newer than the open one (or always, when forced).
select() : array<string|int, array<string|int, mixed>>: Runs a read query against the open build, synchronously. Callers must have waited for {@see ready()}.
setSource() : static: Uses another published build, e.g. a fork's.
disconnect() : void: Drops the connection so the file can be replaced.
download() : PromiseInterface<string|int, void>: Streams a gzipped file, inflating it to `$target` chunk by chunk so it is never held in memory.
inflateTo() : PromiseInterface<string|int, void>: Inflates a gzip body stream into an open file.
install() : PromiseInterface<string|int, string>: Downloads, verifies and swaps in MTGJSON's current build.
label() : string: What this build is called in logs and errors.
open() : void: Opens the build at {@see $path} read-only and reads its version.
prepare() : string: Checks a downloaded build and adds the extra indexes.
refreshQuietly() : void: Refreshes, logging rather than throwing on failure; the open build stays in use.
remoteVersion() : PromiseInterface<string|int, ?string>: The version of the build currently published, from `Meta.json`.
schedule() : void: Starts the refresh timer, and checks right away if the build on disk is already older than one interval.
source() : string: Where the gzipped build is downloaded from.

DEFAULT_REFRESH_INTERVAL

Seconds between `Meta.json` checks by default: MTGJSON rebuilds daily.


    public
        int
    DEFAULT_REFRESH_INTERVAL
    = 86400

DEFAULT_SOURCE

Where the `prices` workflow publishes the build.


    public
        string
    DEFAULT_SOURCE
    = 'https://github.com/Valgorithms/DiscordPHP-MTG/releases/download/prices/prices.sqlite.gz'

FILE

The file name of the installed build.


    public
        string
    FILE
    = 'prices.sqlite'

INDEXES

The build is keyed by uuid already.


    public
        array<string|int, string>
    INDEXES
    = []

JSON_COLUMNS

Columns the SQL build stores as JSON text, by table.


    public
        array<string, array<string|int, string>>
    JSON_COLUMNS
    = ['cards' => ['leadershipSkills', 'relatedCards', 'skuIds', 'sourceProducts'], 'tokens' => ['relatedCards', 'skuIds', 'sourceProducts'], 'cardForeignData' => ['identifiers', 'skuIds'], 'sealedProducts' => ['contents', 'identifiers', 'purchaseUrls'], 'setDecks' => ['commander', 'displayCommander', 'mainBoard', 'planes', 'schemes', 'sealedProductUuids', 'sideBoard', 'sourceSetCodes', 'tokens']]

LIST_COLUMNS

Columns the SQL build stores as `", "`-joined lists, by table.


    public
        array<string, array<string|int, string>>
    LIST_COLUMNS
    = ['cards' => ['artistIds', 'attractionLights', 'availability', 'boosterTypes', 'colorIdentity', 'colorIndicator', 'colors', 'finishes', 'frameEffects', 'keywords', 'originalPrintings', 'otherFaceIds', 'printings', 'producedMana', 'promoTypes', 'rebalancedPrintings', 'subtypes', 'supertypes', 'types', 'variations'], 'tokens' => ['artistIds', 'attractionLights', 'availability', 'boosterTypes', 'colorIdentity', 'colorIndicator', 'colors', 'finishes', 'frameEffects', 'keywords', 'otherFaceIds', 'producedMana', 'promoTypes', 'subtypes', 'supertypes', 'types'], 'sets' => ['languages']]

cardParts and subsets are left as strings, because their values can contain commas.

$browser


        protected
            Browser
    $browser

$columns

Declared column types, by table, read lazily with `PRAGMA table_info`.


        protected
            array<string, array<string, string>>
    $columns
     = []

$date

The date (`meta.date`) of the open build.


        protected
            string|null
    $date
     = null

$http


        protected
            Http
    $http

$logger


        protected
            LoggerInterface
    $logger

$loop


        protected
            LoopInterface
    $loop

$opening

The pending first install, shared by every caller of {@see ready()}.


        protected
            PromiseInterface|null
    $opening
     = null

$path


        protected
            string
    $path

$pdo

The open read-only connection, or null while closed.


        protected
            PDO|null
    $pdo
     = null

$priceColumns

What each price column is: column → medium, provider, kind, finish, currency.


        protected
            array<string, array{medium: string, provider: string, kind: string, finish: string, currency: ?string}>|null
    $priceColumns
     = null

$refreshing

The pending refresh, shared by every caller of {@see refresh()}.


        protected
            PromiseInterface|null
    $refreshing
     = null

$refreshInterval


        protected
            int
    $refreshInterval
     = self::DEFAULT_REFRESH_INTERVAL

$source

The gzipped build's URL; `prices.json` is read from beside it.


        protected
            string
    $source
     = self::DEFAULT_SOURCE

$timer

The periodic refresh timer.


        protected
            TimerInterface|null
    $timer
     = null

$version

The version (`meta.version`) of the open build.


        protected
            string|null
    $version
     = null

__construct()


    public
                    __construct(LoopInterface $loop, LoggerInterface $logger, Http $http, Browser $browser, string $path[, int $refreshInterval = self::DEFAULT_REFRESH_INTERVAL ]) : mixed

Parameters

$loop : LoopInterface: The event loop the download and refresh timer run on.
$logger : LoggerInterface: Logger for download progress and refresh failures.
$http : Http: The MTGJSON HTTP client, used for Meta.json.
$browser : Browser: A browser for the streamed download (no response buffer applies to streams).
$path : string: Where the build is kept, e.g. var/mtgjson/AllPrintings.sqlite.
$refreshInterval : int = self::DEFAULT_REFRESH_INTERVAL: Seconds between Meta.json checks; 0 never refreshes.

close()

Closes the connection and stops the refresh timer. The next query reopens it.


    public
                    close() : void

decode()

Decodes a row of `$table` into MTGJSON's JSON shape: list and JSON columns become arrays, `BOOLEAN` columns become `bool`, and null or empty scalars are dropped.


    public
                    decode(string $table, array<string|int, mixed> $row) : array<string|int, mixed>

Parameters

$table : string: The table the row came from.
$row : array<string|int, mixed>: The raw row.

Return values

array<string|int, mixed> —

The decoded row.

getColumns()

The columns of a table in the open build, with their declared types.


    public
                    getColumns(string $table) : array<string, string>

Parameters

$table : string: The table name.

Return values

array<string, string> —

Column name => declared type (upper case).

getDate()

The date (`meta.date`) of the open build, e.g. `2026-10-03`.


    public
                    getDate() : string|null

Return values

string|null —

Null while no build is open.

getPath()

Where the build is kept.


    public
                    getPath() : string

Return values

string

getVersion()

The version (`meta.version`) of the open build, e.g. `5.3.0+20261003`.


    public
                    getVersion() : string|null

Return values

string|null —

Null while no build is open.

isOpen()

Whether a build is open.


    public
                    isOpen() : bool

Return values

bool

prices()

Today's prices for some cards, nested as MTGJSON nests them but with a single price per point: `medium → provider → {currency, retail|buylist → finish → price}`. Cards without a price are left out; nothing is returned while the build is not open.


    public
                    prices(array<string|int, string> $uuids) : array<string, array<string|int, mixed>>

Parameters

$uuids : array<string|int, string>

Return values

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

Prices, by uuid.

query()

Runs a read query against the build, opening (or downloading) it first.


    public
                    query(string $sql[, array<string|int, mixed> $params = [] ]) : PromiseInterface<string|int, array<string|int, array<string|int, mixed>>>

Parameters

$sql : string: The statement, with ? or named placeholders.
$params : array<string|int, mixed> = []: Values bound to the placeholders.

Return values

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

The raw rows.

ready()

Opens the build, downloading it first if there is none on disk, and starts the refresh timer.


    public
                    ready() : PromiseInterface<string|int, PDO>

Return values

PromiseInterface<string|int, PDO> —

The open connection.

refresh()

Checks `Meta.json` and installs MTGJSON's current build if it is newer than the open one (or always, when forced).


    public
                    refresh([bool $force = false ]) : PromiseInterface<string|int, bool>

Parameters

$force : bool = false: Download even when the versions match.

Return values

PromiseInterface<string|int, bool> —

Whether a new build was installed.

select()

Runs a read query against the open build, synchronously. Callers must have waited for {@see ready()}.


    public
                    select(string $sql[, array<string|int, mixed> $params = [] ]) : array<string|int, array<string|int, mixed>>

Parameters

$sql : string: The statement, with ? or named placeholders.
$params : array<string|int, mixed> = []: Values bound to the placeholders.

Return values

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

The raw rows.

setSource()

Uses another published build, e.g. a fork's.


    public
                    setSource(string $source) : static

Parameters

$source : string: The prices.sqlite.gz URL.

Return values

static

disconnect()

Drops the connection so the file can be replaced.


    protected
                    disconnect() : void

download()

Streams a gzipped file, inflating it to `$target` chunk by chunk so it is never held in memory.


    protected
                    download(string $url, string $target) : PromiseInterface<string|int, void>

Parameters

$url : string: The .gz URL.
$target : string: The file to write the inflated bytes to.

Return values

PromiseInterface<string|int, void>

inflateTo()

Inflates a gzip body stream into an open file.


    protected
                    inflateTo(ReadableStreamInterface $body, resource $file, int $total) : PromiseInterface<string|int, void>

Parameters

$body : ReadableStreamInterface: The response body.
$file : resource: The file to write to.
$total : int: The compressed size, for progress logs (0 when unknown).

Return values

PromiseInterface<string|int, void> —

Resolves once the gzip stream has ended cleanly.

install()

Downloads, verifies and swaps in MTGJSON's current build.


    protected
                    install() : PromiseInterface<string|int, string>

Return values

PromiseInterface<string|int, string> —

The installed version.

label()

What this build is called in logs and errors.


    protected
                    label() : string

Return values

string

open()

Opens the build at {@see $path} read-only and reads its version.


    protected
                    open() : void

prepare()

Checks a downloaded build and adds the extra indexes.


    protected
                    prepare(string $file) : string

Parameters

$file : string: The downloaded file.

Return values

string —

The build's version.

refreshQuietly()

Refreshes, logging rather than throwing on failure; the open build stays in use.


    protected
                    refreshQuietly() : void

remoteVersion()

The version of the build currently published, from `Meta.json`.


    protected
                    remoteVersion() : PromiseInterface<string|int, ?string>

Return values

PromiseInterface<string|int, ?string>

schedule()

Starts the refresh timer, and checks right away if the build on disk is already older than one interval.


    protected
                    schedule() : void

source()

Where the gzipped build is downloaded from.


    protected
                    source() : string

Return values

string

PriceDatabase extends Database in package Application

Tags

Table of Contents

Constants

Properties

Methods

Constants

DEFAULT_REFRESH_INTERVAL

DEFAULT_SOURCE

FILE

Tags

INDEXES

JSON_COLUMNS

LIST_COLUMNS

Properties

$browser

$columns

$date

$http

$logger

$loop

$opening

$path

$pdo

$priceColumns

$refreshing

$refreshInterval

$source

$timer

$version

Methods

__construct()

Parameters

close()

decode()

Parameters

Return values

getColumns()

Parameters

Return values

getDate()

Return values

getPath()

Return values

getVersion()

Return values

isOpen()

Return values

prices()

Parameters

Return values

query()

Parameters

Return values

ready()

Return values

refresh()

Parameters

Return values

select()

Parameters

Tags

Return values

setSource()

Parameters

Return values

disconnect()

download()

Parameters

Return values

inflateTo()

Parameters

Return values

install()

Return values

label()

Tags

Return values

open()

Tags

PriceDatabase extends Database
in package

Application