1. class
  2. Nette
  3. \
  4. Database
  5. \
  6. Table
  7. \
  8. Selection

Selection

class Selection implements Iterator, IRowContainer, ArrayAccess, Countable

Represents filtered table result.

Selection is based on the great library NotORM http://www.notorm.com written by Jakub Vrana.

Properties

protected $explorer
protected $context

back compatibility
protected $conventions
protected $cache
protected $sqlBuilder
protected $name

table name
protected string|string[]|null $primary
protected $primarySequence

primary column sequence name, false for autodetection
protected T[] $rows
protected T[] $data
protected $dataRefreshed
protected $globalRefCache

cache array of Selection and GroupedSelection prototypes
protected $refCache
protected $generalCacheKey
protected $specificCacheKey
protected array<string,array<int|Row|ActiveRow>> $aggregation
protected array<string,bool>|false|null $accessedColumns
protected array<string,bool>|false|null $previousAccessedColumns
protected $observeCache
protected list<string|int> $keys

Methods

__construct(Explorer $explorer, Conventions $conventions, string $tableName, Storage|null $cacheStorage = null)

Creates filtered table representation.

__destruct()

No description

__clone()

No description

string
getName()

No description

string|array|null
getPrimary(bool $throw = true)

Returns table primary key.

string|null
getPrimarySequence()

No description

Selection
setPrimarySequence(string $sequence)

No description

string
getSql()

No description

array
getPreviousAccessedColumns()

Loads cache of previous accessed columns and returns it.

SqlBuilder
getSqlBuilder()

No description

Explorer
getExplorer()

No description

ActiveRow|null
get(mixed $key)

Returns row specified by primary key.

ActiveRow|null
fetch()

Returns the next row or null if there are no more rows.

mixed
fetchField(string|null $column = null) deprecated

Fetches single field.

array
fetchPairs(string|int|Closure|null $keyOrCallback = null, string|int|null $value = null)

Returns all rows as associative array, where first argument specifies key column and second value column.

array
fetchAll()

Returns all rows as an array indexed by primary key.

array
fetchAssoc(string $path) deprecated

Returns all rows as associative tree.

Selection
select(string $columns, mixed ...$params)

Adds select clause, more calls append to the end.

Selection
wherePrimary(mixed $key)

Adds condition for primary key.

Selection
where(string|array $condition, mixed ...$params)

Adds where condition, more calls append with AND.

Selection
joinWhere(string $tableChain, string $condition, mixed ...$params)

Adds ON condition when joining specified table, more calls appends with AND.

void
condition(string|array $condition, array $params, string|null $tableChain = null)

Adds a WHERE or JOIN condition. When $tableChain is given, the condition is added to the JOIN ON clause.

Selection
whereOr(array $parameters)

Adds where condition using the OR operator between parameters.

Selection
order(string $columns, mixed ...$params)

Adds ORDER BY clause, more calls appends to the end.

Selection
limit(int|null $limit, int|null $offset = null)

Sets LIMIT clause, more calls rewrite old values.

Selection
page(int $page, int $itemsPerPage, int|null $numOfPages = null)

Sets LIMIT and OFFSET for the given page number. Optionally calculates total number of pages.

Selection
group(string $columns, mixed ...$params)

Sets GROUP BY clause, more calls rewrite old value.

Selection
having(string $having, mixed ...$params)

Sets HAVING clause, more calls rewrite old value.

Selection
alias(string $tableChain, string $alias)

Aliases table. Example ':book:book_tag.tag', 'tg'

mixed
aggregation(string $function, string|null $groupFunction = null)

Executes aggregation function.

int
count(string|null $column = null)

Returns count of fetched rows, or runs COUNT($column) query when column is specified.

mixed
min(string $column)

Returns minimum value from a column.

mixed
max(string $column)

Returns maximum value from a column.

mixed
sum(string $column)

Returns sum of values in a column.

void
execute()

No description

ActiveRow
createRow(array $row) deprecated

No description

Selection
createSelectionInstance(string|null $table = null) deprecated

No description

GroupedSelection
createGroupedSelectionInstance(string $table, string $column) deprecated

No description

ResultSet
query(string $query)

No description

void
emptyResultSet(bool $clearCache = true, bool $deleteReferencedCache = true)

No description

void
saveCacheState()

No description

Selection
getRefTable(mixed $refPath)

Returns the root Selection used as the shared cache anchor for referenced rows.

void
loadRefCache()

Initializes the reference cache for the current selection. Overridden by GroupedSelection.

string
getGeneralCacheKey()

Returns general cache key independent of query parameters or SQL limit.

string
getSpecificCacheKey()

Returns object-specific cache key dependent on query parameters.

bool
accessColumn(string|null $key, bool $selectColumn = true)

No description

void
removeAccessColumn(string $key)

No description

bool
getDataRefreshed()

Checks whether the selection re-queried for additional columns.

ActiveRow|array|int
insert(iterable $data)

Inserts one or more rows into the table.

int
update(iterable $data)

Updates all rows matching current conditions. JOINs in UPDATE are supported only by MySQL.

int
delete()

Deletes all rows matching current conditions.

ActiveRow|false|null
getReferencedTable(ActiveRow $row, string|null $table, string|null $column = null)

Returns a referenced (parent) row for a belongs-to relationship.

GroupedSelection|null
getReferencingTable(string $table, string|null $column = null, int|string|null $active = null)

Returns a grouped selection of referencing (child) rows for a has-many relationship.

void
rewind()

No description

ActiveRow|false
current()

No description

string|int
key()

No description

void
next()

No description

bool
valid()

No description

void
offsetSet(string|int $key, T $value)

Sets a row by primary key.

ActiveRow|null
offsetGet(string|int $key)

Returns specified row.

bool
offsetExists(string|int $key)

Tests if row exists.

void
offsetUnset(string|int $key)

Removes row from result set.

Details

at line 76
__construct(Explorer $explorer, Conventions $conventions, string $tableName, Storage|null $cacheStorage = null)

Creates filtered table representation.

Parameters

Explorer $explorer
Conventions $conventions
string $tableName
Storage|null $cacheStorage

at line 95
__destruct()

No description

at line 101
__clone()

No description

at line 107
string getName()

No description

Return Value

string

at line 117
string|array|null getPrimary(bool $throw = true)

Returns table primary key.

Parameters

bool $throw

Return Value

string|array|null

at line 127
string|null getPrimarySequence()

No description

Return Value

string|null

at line 137
Selection setPrimarySequence(string $sequence)

No description

Parameters

string $sequence

Return Value

Selection

at line 144
string getSql()

No description

Return Value

string

at line 155
array getPreviousAccessedColumns()

internal  
 

Loads cache of previous accessed columns and returns it.

Return Value

array

at line 171
SqlBuilder getSqlBuilder()

internal  
 

No description

Return Value

SqlBuilder

at line 177
Explorer getExplorer()

No description

Return Value

Explorer

at line 190
ActiveRow|null get(mixed $key)

Returns row specified by primary key.

Parameters

mixed $key

Return Value

ActiveRow|null

at line 201
ActiveRow|null fetch()

Returns the next row or null if there are no more rows.

Return Value

ActiveRow|null

at line 218
mixed fetchField(string|null $column = null) deprecated

deprecated

Fetches single field.

Parameters

string|null $column

Return Value

mixed

at line 240
array fetchPairs(string|int|Closure|null $keyOrCallback = null, string|int|null $value = null)

Returns all rows as associative array, where first argument specifies key column and second value column.

For duplicate keys, the last value is used. When using null as key, array is indexed from zero. Alternatively accepts callback returning value or key-value pairs.

Parameters

string|int|Closure|null $keyOrCallback
string|int|null $value

Return Value

array

at line 250
array fetchAll()

Returns all rows as an array indexed by primary key.

Return Value

array

at line 261
array fetchAssoc(string $path) deprecated

deprecated

Returns all rows as associative tree.

Parameters

string $path

Return Value

array

at line 275
Selection select(string $columns, mixed ...$params)

Adds select clause, more calls append to the end.

Parameters

string $columns

for example "column, MD5(column) AS column_md5"
mixed ...$params

Return Value

Selection

at line 286
Selection wherePrimary(mixed $key)

Adds condition for primary key.

Parameters

mixed $key

Return Value

Selection

at line 315
Selection where(string|array $condition, mixed ...$params)

Adds where condition, more calls append with AND.

Parameters

string|array $condition

possibly containing ?
mixed ...$params

Return Value

Selection

at line 327
Selection joinWhere(string $tableChain, string $condition, mixed ...$params)

Adds ON condition when joining specified table, more calls appends with AND.

Parameters

string $tableChain

table chain or table alias for which you need additional left join condition
string $condition

possibly containing ?
mixed ...$params

Return Value

Selection

at line 339
protected void condition(string|array $condition, array $params, string|null $tableChain = null)

Adds a WHERE or JOIN condition. When $tableChain is given, the condition is added to the JOIN ON clause.

Parameters

string|array $condition

possibly containing ?
array $params
string|null $tableChain

Return Value

void

at line 364
Selection whereOr(array $parameters)

Adds where condition using the OR operator between parameters.

More calls appends with AND.

Parameters

array $parameters

['column1' => 1, 'column2 > ?' => 2, 'full condition']

Return Value

Selection

Exceptions

InvalidArgumentException

at line 398
Selection order(string $columns, mixed ...$params)

Adds ORDER BY clause, more calls appends to the end.

Parameters

string $columns

for example 'column1, column2 DESC'
mixed ...$params

Return Value

Selection

at line 409
Selection limit(int|null $limit, int|null $offset = null)

Sets LIMIT clause, more calls rewrite old values.

Parameters

int|null $limit
int|null $offset

Return Value

Selection

at line 420
Selection page(int $page, int $itemsPerPage, int|null $numOfPages = null)

Sets LIMIT and OFFSET for the given page number. Optionally calculates total number of pages.

Parameters

int $page
int $itemsPerPage
int|null $numOfPages

Return Value

Selection

at line 437
Selection group(string $columns, mixed ...$params)

Sets GROUP BY clause, more calls rewrite old value.

Parameters

string $columns
mixed ...$params

Return Value

Selection

at line 448
Selection having(string $having, mixed ...$params)

Sets HAVING clause, more calls rewrite old value.

Parameters

string $having
mixed ...$params

Return Value

Selection

at line 459
Selection alias(string $tableChain, string $alias)

Aliases table. Example ':book:book_tag.tag', 'tg'

Parameters

string $tableChain
string $alias

Return Value

Selection

at line 473
mixed aggregation(string $function, string|null $groupFunction = null)

Executes aggregation function.

Parameters

string $function

select call in "FUNCTION(column)" format
string|null $groupFunction

Return Value

mixed

at line 496
int count(string|null $column = null)

Returns count of fetched rows, or runs COUNT($column) query when column is specified.

Parameters

string|null $column

Return Value

int

at line 510
mixed min(string $column)

Returns minimum value from a column.

Parameters

string $column

Return Value

mixed

at line 519
mixed max(string $column)

Returns maximum value from a column.

Parameters

string $column

Return Value

mixed

at line 528
mixed sum(string $column)

Returns sum of values in a column.

Parameters

string $column

Return Value

mixed

at line 537
protected void execute()

No description

Return Value

void

at line 583
protected ActiveRow createRow(array $row) deprecated

deprecated

No description

Parameters

array $row

Return Value

ActiveRow

at line 594
Selection createSelectionInstance(string|null $table = null) deprecated

deprecated

No description

Parameters

string|null $table

Return Value

Selection

at line 604
protected GroupedSelection createGroupedSelectionInstance(string $table, string $column) deprecated

deprecated

No description

Parameters

string $table
string $column

Return Value

GroupedSelection

at line 610
protected ResultSet query(string $query)

No description

Parameters

string $query

Return Value

ResultSet

at line 616
protected void emptyResultSet(bool $clearCache = true, bool $deleteReferencedCache = true)

No description

Parameters

bool $clearCache
bool $deleteReferencedCache

Return Value

void

at line 638
protected void saveCacheState()

No description

Return Value

void

at line 668
protected Selection getRefTable(mixed $refPath)

Returns the root Selection used as the shared cache anchor for referenced rows.

Parameters

mixed $refPath

Return Value

Selection

at line 678
protected void loadRefCache()

Initializes the reference cache for the current selection. Overridden by GroupedSelection.

Return Value

void

at line 687
protected string getGeneralCacheKey()

Returns general cache key independent of query parameters or SQL limit.

Used e.g. for previously accessed columns caching.

Return Value

string

at line 710
protected string getSpecificCacheKey()

Returns object-specific cache key dependent on query parameters.

Used e.g. for reference memory caching.

Return Value

string

at line 725
bool accessColumn(string|null $key, bool $selectColumn = true)

internal  
 

No description

Parameters

string|null $key

column name or null to reload all columns
bool $selectColumn

Return Value

bool

if selection requeried for more columns.

at line 791
void removeAccessColumn(string $key)

internal  
 

No description

Parameters

string $key

Return Value

void

at line 802
bool getDataRefreshed()

Checks whether the selection re-queried for additional columns.

Return Value

bool

at line 817
ActiveRow|array|int insert(iterable $data)

Inserts one or more rows into the table.

Returns the inserted ActiveRow for single-row inserts, or the number of affected rows otherwise.

Parameters

iterable $data

Return Value

ActiveRow|array|int

at line 902
int update(iterable $data)

Updates all rows matching current conditions. JOINs in UPDATE are supported only by MySQL.

Parameters

iterable $data

Return Value

int

number of affected rows

at line 923
int delete()

Deletes all rows matching current conditions.

Return Value

int

number of affected rows

at line 938
ActiveRow|false|null getReferencedTable(ActiveRow $row, string|null $table, string|null $column = null)

Returns a referenced (parent) row for a belongs-to relationship.

Returns null if the referenced row does not exist, false if the relationship is not defined.

Parameters

ActiveRow $row
string|null $table
string|null $column

Return Value

ActiveRow|false|null

at line 990
GroupedSelection|null getReferencingTable(string $table, string|null $column = null, int|string|null $active = null)

Returns a grouped selection of referencing (child) rows for a has-many relationship.

Parameters

string $table
string|null $column
int|string|null $active

Return Value

GroupedSelection|null

at line 1027
void rewind()

No description

Return Value

void

at line 1036
ActiveRow|false current()

No description

Return Value

ActiveRow|false

at line 1045
string|int key()

No description

Return Value

string|int

at line 1052
void next()

No description

Return Value

void

at line 1060
bool valid()

No description

Return Value

bool

at line 1074
void offsetSet(string|int $key, T $value)

Sets a row by primary key.

Parameters

string|int $key
T $value

Return Value

void

at line 1086
ActiveRow|null offsetGet(string|int $key)

Returns specified row.

Parameters

string|int $key

Return Value

ActiveRow|null

at line 1097
bool offsetExists(string|int $key)

Tests if row exists.

Parameters

string|int $key

Return Value

bool

at line 1108
void offsetUnset(string|int $key)

Removes row from result set.

Parameters

string|int $key

Return Value

void