DiscordPHP-MTG Documentation

Query
in package

Application

AbstractYes

Compiles a search — the same `key => value` filters the old api.magicthegathering.io took — into SQL against the AllPrintings build.

Filter values keep that API's conventions: | separates alternatives (logical or) and, for fields holding several values such as colors, , requires all of them (logical and), so colors=R,G|U means "red and green, or blue". Text fields match partially and case-insensitively; a value in double quotes matches exactly. Numbers accept a gt/gte/lt/lte (or >/>=/</<=) prefix.

Column names are only ever taken from the build's own schema, so filter keys cannot inject SQL; values are always bound.

Each condition helper returns [sql, bindings] (sql is null when the value held no terms), so conditions can be combined or nested before where() adds them.

Constants

MAX_PAGE_SIZE : int = 100: The largest page a query may return.

Properties

$bindings : array<string|int, mixed>: Values bound to the conditions' placeholders, in order.
$database : Database
$joins : array<string, string>: Joined tables, by table name, as SQL fragments.
$limit : int|null: Page size, or null for no limit.
$offset : int: Rows to skip.
$order : array<string|int, string>: `ORDER BY` terms.
$orderBindings : array<string|int, mixed>: Values bound to the ordering's placeholders, in order.
$table : string: The primary table.
$where : array<string|int, string>: Conditions, combined with `AND`.

Methods

__construct() : mixed
count() : int: How many rows match, ignoring the page.
filter() : static: Applies a set of filters and query modifiers.
get() : array<string|int, array<string|int, mixed>>: Runs the compiled statement and decodes each row.
getBindings() : array<string|int, mixed>: The values bound to the compiled statement's placeholders.
toSql() : string: The compiled statement.
alternatives() : array<string|int, array<string|int, string>>: Splits a filter value into alternatives (`|`), each a list of terms that must all hold (`,`) when `$and` is set.
combine() : array{0: ?string, 1: array}: Combines conditions with `OR` (or `AND`).
compare() : array{0: ?string, 1: array}: Numeric match, with an optional comparison prefix per alternative.
contains() : array{0: ?string, 1: array}: Matches a `", "`-joined list column: every term of an alternative must be in the list.
direction() : array{0: string, 1: string}: Parses an `orderBy` value: a field, optionally prefixed with `-` or suffixed with ` desc`/` asc`.
equals() : array{0: ?string, 1: array}: Exact, case-insensitive match.
exact() : array{0: ?string, 1: array}: Exact match on a column stored in one case (set codes, UUIDs), so its index still applies.
flag() : array{0: string, 1: array}: Matches a `BOOLEAN` column, where the build stores false as `0` or null.
like() : array{0: ?string, 1: array}: Partial, case-insensitive text match against one or more columns; a value in double quotes matches exactly.
normalize() : array<string|int, mixed>: Normalizes filter keys to camelCase (`color_identity` → `colorIdentity`) and drops empty values.
orderBy() : void: Adds an `ORDER BY` term.
paginate() : void: Applies `page` and `pageSize`.
placeholders() : string: `?, ?, ?` for a list of values.
present() : array{0: string, 1: array}: Requires a column to hold a value.
scalar() : string: Converts a scalar filter value to a string.
select() : string: The select list.
terms() : array<string|int, string>: The first term of each alternative, for single-valued fields.
truthy() : bool: Reads a boolean-ish filter value.
where() : void: Adds a condition.

MAX_PAGE_SIZE

The largest page a query may return.


    public
        int
    MAX_PAGE_SIZE
    = 100

$bindings

Values bound to the conditions' placeholders, in order.


        protected
            array<string|int, mixed>
    $bindings
     = []

$database


        protected
            Database
    $database

$joins

Joined tables, by table name, as SQL fragments.


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

$limit

Page size, or null for no limit.


        protected
            int|null
    $limit
     = null

$offset

Rows to skip.


        protected
            int
    $offset
     = 0

$order

`ORDER BY` terms.


        protected
            array<string|int, string>
    $order
     = []

$orderBindings

Values bound to the ordering's placeholders, in order.


        protected
            array<string|int, mixed>
    $orderBindings
     = []

$table

The primary table.


        protected
            string
    $table

$where

Conditions, combined with `AND`.


        protected
            array<string|int, string>
    $where
     = []

__construct()


    public
                    __construct(Database $database) : mixed

Parameters

$database : Database: An open build; its schema decides which filters exist.

count()

How many rows match, ignoring the page.


    public
                    count() : int

Return values

int

filter()

Applies a set of filters and query modifiers.


    public
    abstract                filter(array<string|int, mixed> $filters) : static

Parameters

$filters : array<string|int, mixed>: key => value; keys may be snake_case or camelCase.

Return values

static

get()

Runs the compiled statement and decodes each row.


    public
                    get() : array<string|int, array<string|int, mixed>>

Return values

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

getBindings()

The values bound to the compiled statement's placeholders.


    public
                    getBindings() : array<string|int, mixed>

Return values

array<string|int, mixed>

toSql()

The compiled statement.


    public
                    toSql() : string

Return values

string

alternatives()

Splits a filter value into alternatives (`|`), each a list of terms that must all hold (`,`) when `$and` is set.


    protected
            static        alternatives(mixed $value[, bool $and = false ]) : array<string|int, array<string|int, string>>

Parameters

$value : mixed: The filter value; an array is a list of alternatives.
$and : bool = false: Whether , separates required terms.

Return values

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

combine()

Combines conditions with `OR` (or `AND`).


    protected
            static        combine(array<string|int, array{0: ?string, 1: array}> $conditions[, string $operator = 'OR' ]) : array{0: ?string, 1: array}

Parameters

$conditions : array<string|int, array{0: ?string, 1: array}>
$operator : string = 'OR': OR or AND.

Return values

array{0: ?string, 1: array}

compare()

Numeric match, with an optional comparison prefix per alternative.


    protected
            static        compare(string $column, mixed $value) : array{0: ?string, 1: array}

Parameters

$column : string: Qualified column name.
$value : mixed: E.g. 3, gte3, >=3, 2|5.

Return values

array{0: ?string, 1: array}

contains()

Matches a `", "`-joined list column: every term of an alternative must be in the list.


    protected
            static        contains(string $column, mixed $value[, callable|null $map = null ]) : array{0: ?string, 1: array}

Parameters

$column : string: Qualified column name.
$value : mixed
$map : callable|null = null: Maps each term before matching; returning '' matches an empty list.

Return values

array{0: ?string, 1: array}

direction()

Parses an `orderBy` value: a field, optionally prefixed with `-` or suffixed with ` desc`/` asc`.


    protected
            static        direction(string $value) : array{0: string, 1: string}

Parameters

$value : string

Return values

array{0: string, 1: string} —

The field and ASC/DESC.

equals()

Exact, case-insensitive match.


    protected
            static        equals(string $column, mixed $value) : array{0: ?string, 1: array}

Parameters

$column : string: Qualified column name.
$value : mixed

Return values

array{0: ?string, 1: array}

exact()

Exact match on a column stored in one case (set codes, UUIDs), so its index still applies.


    protected
            static        exact(string $column, mixed $value, callable $normalize) : array{0: ?string, 1: array}

Parameters

$column : string: Qualified column name.
$value : mixed
$normalize : callable: Puts each term in the stored case, e.g. strtoupper.

Return values

array{0: ?string, 1: array}

flag()

Matches a `BOOLEAN` column, where the build stores false as `0` or null.


    protected
            static        flag(string $column, mixed $value) : array{0: string, 1: array}

Parameters

$column : string: Qualified column name.
$value : mixed: true/false, 1/0, yes/no.

Return values

array{0: string, 1: array}

like()

Partial, case-insensitive text match against one or more columns; a value in double quotes matches exactly.


    protected
            static        like(array<string|int, string> $columns, mixed $value) : array{0: ?string, 1: array}

Parameters

$columns : array<string|int, string>: Qualified column names; a match on any counts.
$value : mixed

Return values

array{0: ?string, 1: array}

normalize()

Normalizes filter keys to camelCase (`color_identity` → `colorIdentity`) and drops empty values.


    protected
            static        normalize(array<string|int, mixed> $filters) : array<string|int, mixed>

Parameters

$filters : array<string|int, mixed>

Return values

array<string|int, mixed>

orderBy()

Adds an `ORDER BY` term.


    protected
                    orderBy(string $term[, array<string|int, mixed> $bindings = [] ]) : void

Parameters

$term : string: SQL, with ? placeholders.
$bindings : array<string|int, mixed> = []: Values for the placeholders.

paginate()

Applies `page` and `pageSize`.


    protected
                    paginate(mixed $page, mixed $pageSize) : void

Parameters

$page : mixed: 1-based page.
$pageSize : mixed: Rows per page, 1-100.

placeholders()

`?, ?, ?` for a list of values.


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

Parameters

$values : array<string|int, mixed>

Return values

string

present()

Requires a column to hold a value.


    protected
            static        present(string $column) : array{0: string, 1: array}

Parameters

$column : string: Qualified column name.

Return values

array{0: string, 1: array}

scalar()

Converts a scalar filter value to a string.


    protected
            static        scalar(mixed $value) : string

Parameters

$value : mixed

Return values

string

select()

The select list.


    protected
                    select() : string

Return values

string

terms()

The first term of each alternative, for single-valued fields.


    protected
            static        terms(mixed $value) : array<string|int, string>

Parameters

$value : mixed

Return values

array<string|int, string>

truthy()

Reads a boolean-ish filter value.


    protected
            static        truthy(mixed $value) : bool

Parameters

$value : mixed

Return values

bool

where()

Adds a condition.


    protected
                    where(array{0: ?string, 1: array} $condition) : void

Parameters

$condition : array{0: ?string, 1: array}: [sql, bindings]; a null sql adds nothing.

Query in package Application

Tags

Table of Contents

Constants

Properties

Methods

Constants

MAX_PAGE_SIZE

Properties

$bindings

$database

$joins

$limit

$offset

$order

$orderBindings

$table

$where

Methods

__construct()

Parameters

count()

Return values

filter()

Parameters

Tags

Return values

get()

Return values

getBindings()

Return values

toSql()

Return values

alternatives()

Parameters

Return values

combine()

Parameters

Return values

compare()

Parameters

Tags

Return values

contains()

Parameters

Return values

direction()

Parameters

Return values

equals()

Parameters

Return values

exact()

Parameters

Return values

flag()

Parameters

Return values

like()

Parameters

Return values

normalize()

Parameters

Return values

orderBy()

Parameters

paginate()

Parameters

Tags

placeholders()

Parameters

Return values

present()

Parameters

Return values

scalar()

Parameters

Tags

Return values

select()

Query
in package

Application