QueryBuilder

class QueryBuilder implements Countable

This class can be used to search for models with specific characteristics in the database.

Note that most methods of this class return itself, so that you can easily add a number of different filters.

return Team::getQueryBuilder() ->active() ->where('name')->startsWith('a') ->sortBy('name')->reverse() ->getModels();

Methods

__construct(string $type, array $options = array())

Create a new QueryBuilder

QueryBuilder
where(string $column)

Select a column

QueryBuilder
equals(string $string)

Request that a column equals a string (case-insensitive)

QueryBuilder
notEquals(string $string)

Request that a column doesNOT equals a string (case-insensitive)

QueryBuilder
greaterThan(string $quantity)

Request that a column is greater than a quantity

QueryBuilder
lessThan(string $quantity)

Request that a column is less than a quantity

QueryBuilder
isBefore(string|TimeDate $time, bool $inclusive = false, bool $reverse = false)

Request that a timestamp is before the specified time

QueryBuilder
isAfter(string|TimeDate $time, bool $inclusive = false, bool $reverse = false)

Request that a timestamp is after the specified time

QueryBuilder
is(int|Model|null $number)

Request that a column equals a number

QueryBuilder
isOneOf(string[] $strings)

Request that a column equals one of some strings

QueryBuilder
startsWith(string $string)

Request that a column value starts with a string (case-insensitive)

QueryBuilder
except(Model|int $model)

Request that a specific model is not returned

QueryBuilder
sortBy(string $column)

Return the results sorted by the value of a column

QueryBuilder
reverse()

Reverse the order

QueryBuilder
limit(int $count)

Specify the number of results per page

QueryBuilder
fromPage(int|null $page)

Only show results from a specific page

QueryBuilder
endAt(int|Model $model, bool $inclusive = false, bool $reverse = false)

End with a specific result

QueryBuilder
startAt(int|Model $model, bool $inclusive = false, bool $reverse = false)

Start with a specific result

QueryBuilder
active()

Request that only "active" Models should be returned

QueryBuilder
visibleTo(Player $player, bool $showDeleted = false)

Make sure that Models invisible to a player are not returned

string[]
getNames()

Perform the query and get back the results in an array of names

array[]
getArray(string|string[] $columns)

Perform the query and get back the results in a list of arrays

void
addToCache(bool $fastFetch = true)

An alias for QueryBuilder::getModels(), with fast fetching on by default and no return of results

array
getModels(bool $fastFetch = false)

Perform the query and get the results as Models

int
count()

Count the results

countPages()

Count the number of pages that all the models could be separated into

bool
any()

Find if there is any result

int
getResultsPerPage()

Get the amount of results that are returned per page

Details

at line line 139
__construct(string $type, array $options = array())

Create a new QueryBuilder

A new query builder should be created on a static getQueryBuilder() method on each model. The options array can contain the following properties:

  • columns: An associative array - the key of each entry is the column name that will be used by other methods, while the value is is the column name that is used in the database structure

  • activeStatuses: If the model has a status column, this should be a list of values that make the entry be considered "active"

  • name: The name of the column which represents the name of the object

Parameters

string $type The type of the Model (e.g. "Player" or "Match")
array $options The options to pass to the builder (see above)

at line line 160
QueryBuilder where(string $column)

Select a column

$queryBuilder->where('username')->equals('administrator');

Parameters

string $column The column to select

Return Value

QueryBuilder

at line line 177
QueryBuilder equals(string $string)

Request that a column equals a string (case-insensitive)

Parameters

string $string The string that the column's value should equal to

Return Value

QueryBuilder

at line line 190
QueryBuilder notEquals(string $string)

Request that a column doesNOT equals a string (case-insensitive)

Parameters

string $string The string that the column's value should equal to

Return Value

QueryBuilder

at line line 203
QueryBuilder greaterThan(string $quantity)

Request that a column is greater than a quantity

Parameters

string $quantity The quantity to test against

Return Value

QueryBuilder

at line line 216
QueryBuilder lessThan(string $quantity)

Request that a column is less than a quantity

Parameters

string $quantity The quantity to test against

Return Value

QueryBuilder

at line line 232
QueryBuilder isBefore(string|TimeDate $time, bool $inclusive = false, bool $reverse = false)

Request that a timestamp is before the specified time

Parameters

string|TimeDate $time The timestamp to compare to
bool $inclusive Whether to include the given timestamp
bool $reverse Whether to reverse the results

Return Value

QueryBuilder

at line line 246
QueryBuilder isAfter(string|TimeDate $time, bool $inclusive = false, bool $reverse = false)

Request that a timestamp is after the specified time

Parameters

string|TimeDate $time The timestamp to compare to
bool $inclusive Whether to include the given timestamp
bool $reverse Whether to reverse the results

Return Value

QueryBuilder

at line line 268
QueryBuilder is(int|Model|null $number)

Request that a column equals a number

Parameters

int|Model|null $number The number that the column's value should equal to. If a Model is provided, use the model's ID, while null values are ignored.

Return Value

QueryBuilder

at line line 290
QueryBuilder isOneOf(string[] $strings)

Request that a column equals one of some strings

Parameters

string[] $strings The list of accepted values for the column

Return Value

QueryBuilder

at line line 309
QueryBuilder startsWith(string $string)

Request that a column value starts with a string (case-insensitive)

Parameters

string $string The substring that the column's value should start with

Return Value

QueryBuilder

at line line 322
QueryBuilder except(Model|int $model)

Request that a specific model is not returned

Parameters

Model|int $model The ID or model you don't want to get

Return Value

QueryBuilder

at line line 340
QueryBuilder sortBy(string $column)

Return the results sorted by the value of a column

Parameters

string $column The column based on which the results should be ordered

Return Value

QueryBuilder

at line line 358
QueryBuilder reverse()

Reverse the order

Note: This only works if you have specified a column in the sortBy() method

Return Value

QueryBuilder

at line line 371
QueryBuilder limit(int $count)

Specify the number of results per page

Parameters

int $count The number of results

Return Value

QueryBuilder

at line line 384
QueryBuilder fromPage(int|null $page)

Only show results from a specific page

Parameters

int|null $page The page number (or null to show all pages - counting starts from 0)

Return Value

QueryBuilder

at line line 399
QueryBuilder endAt(int|Model $model, bool $inclusive = false, bool $reverse = false)

End with a specific result

Parameters

int|Model $model The model (or database ID) after the first result
bool $inclusive Whether to include the provided model
bool $reverse Whether to reverse the results

Return Value

QueryBuilder

at line line 412
QueryBuilder startAt(int|Model $model, bool $inclusive = false, bool $reverse = false)

Start with a specific result

Parameters

int|Model $model The model (or database ID) before the first result
bool $inclusive Whether to include the provided model
bool $reverse Whether to reverse the results

Return Value

QueryBuilder

at line line 445
QueryBuilder active()

Request that only "active" Models should be returned

Return Value

QueryBuilder

at line line 467
QueryBuilder visibleTo(Player $player, bool $showDeleted = false)

Make sure that Models invisible to a player are not returned

Note that this method does not take PermissionModel::canBeSeenBy() into consideration for performance purposes, so you will have to override this in your query builder if necessary.

Parameters

Player $player The player in question
bool $showDeleted false to hide deleted models even from admins

Return Value

QueryBuilder

at line line 491
string[] getNames()

Perform the query and get back the results in an array of names

Return Value

string[] An array of the type $id => $name

at line line 509
array[] getArray(string|string[] $columns)

Perform the query and get back the results in a list of arrays

Parameters

string|string[] $columns The column(s) that should be returned

Return Value

array[]

at line line 529
void addToCache(bool $fastFetch = true)

An alias for QueryBuilder::getModels(), with fast fetching on by default and no return of results

Parameters

bool $fastFetch Whether to perform one query to load all the model data instead of fetching them one by one

Return Value

void

at line line 543
array getModels(bool $fastFetch = false)

Perform the query and get the results as Models

Parameters

bool $fastFetch Whether to perform one query to load all the model data instead of fetching them one by one (ignores cache)

Return Value

array

at line line 564
int count()

Count the results

Return Value

int

at line line 581
countPages()

Count the number of pages that all the models could be separated into

at line line 591
bool any()

Find if there is any result

Return Value

bool

at line line 605
int getResultsPerPage()

Get the amount of results that are returned per page

Return Value

int