DatabaseCollection
extends Collection
in package
DatabaseCollection a Collection interface to a database result.
It will lazyily generate & mutate the SQL query based on the filter & sorting operations. Inspired by "Linq to SQL".
Table of Contents
- $data : Traversable
- The traversable the Collection class operates on.
- $dbLink : string
- The database identifier. (default: "default").
- $events : array<string|int, mixed>
- Allow listening to the events: 'changing' and 'changed'.
- $__kvo : array<string|int, mixed>
- Storage array for the properties with KVO (Key Value Observer) listeners.
- $sql : Sql|string
- The SQL object or string fetches the items in this collection.
- __call() : mixed
- Report that the $method doesn't exist.
- __callStatic() : mixed
- Report that the $method doesn't exist.
- __clone() : mixed
- Clone a database collection.
- __construct() : mixed
- Constructor.
- __get() : mixed
- Report that $property doesn't exist.
- __set() : mixed
- Report that $property doesn't exist and set the property to the given $value.
- __toString() : string
- The object is used as an string.
- count() : int
- Returns the number of elements in the collection.
- find() : mixed
- Returns the first item that matches the conditions.
- getIterator() : Iterator
- getQuery() : string|Sql
- Inspect the SQL query.
- hasEvent() : bool
- Check id the $event is a registered event.
- indexOf() : mixed|null
- Returns the the key of first item that matches the conditions.
- map() : Collection
- Creates a new collection with all values converted by the callback.
- max() : mixed
- Return the highest value.
- min() : mixed
- Return the lowest value.
- off() : mixed
- Remove a callback from an event.
- offsetExists() : bool
- Whether a offset exists.
- offsetGet() : mixed
- Offset to retrieve.
- offsetSet() : mixed
- Offset to set.
- offsetUnset() : mixed
- Offset to unset.
- on() : string
- Add a callback for an event.
- orderBy() : Collection
- Return a new collection sorted by the given field in ascending order.
- orderByDescending() : Collection
- Return a new collection sorted by the given field in descending order.
- reduce() : mixed
- Iteratively reduce the collection to a single value using a callback function.
- remove() : bool
- Remove one or more items from the this collection.
- reverse() : Collection
- Return a new collection in the reverse order.
- select() : Collection
- Return a new collection where each element is a subselection of the original element.
- selectKey() : Collection
- Returns a new collection where the key is based on a property.
- setQuery() : mixed
- Override the SQL query.
- skip() : Collection
- Return a new Collection without the first x items.
- take() : Collection
- Return a new Collection with only the first x items.
- toArray() : array<string|int, mixed>
- Return the collection as an array.
- trigger() : mixed
- Trigger an event.
- where() : Collection
- Return a subsection of the collection based on the conditions.
- buildFilter() : callable
- Build a closure which validates an item with the gives $conditions.
- dataToArray() : mixed
- Converts $this->data into an array.
- convertPathToColumn() : mixed
- Convert a path to a (escaped) columnname.
- quote() : mixed
- Don't put quotes around number for columns that are assumend to be integers ('id' or ending in '_id').
Properties
$data
The traversable the Collection class operates on.
protected
Traversable
$data
Iterator / array
$dbLink
The database identifier. (default: "default").
protected
string
$dbLink
$events
Allow listening to the events: 'changing' and 'changed'.
protected
array<string|int, mixed>
$events
= array('adding' => [], 'added' => [], 'removing' => [], 'removed' => [])
$__kvo
Storage array for the properties with KVO (Key Value Observer) listeners.
private
array<string|int, mixed>
$__kvo
= []
$sql
The SQL object or string fetches the items in this collection.
private
Sql|string
$sql
Methods
__call()
Report that the $method doesn't exist.
public
__call(string $method, array<string|int, mixed> $arguments) : mixed
Parameters
- $method : string
- $arguments : array<string|int, mixed>
Return values
mixed —__callStatic()
Report that the $method doesn't exist.
public
static __callStatic(string $method, array<string|int, mixed> $arguments) : mixed
Parameters
- $method : string
- $arguments : array<string|int, mixed>
Return values
mixed —__clone()
Clone a database collection.
public
__clone() : mixed
Return values
mixed —__construct()
Constructor.
public
__construct(Sql|string $sql[, string $dbLink = 'default' ]) : mixed
Parameters
- $sql : Sql|string
-
The SELECT query.
- $dbLink : string = 'default'
-
The database identifier.
Return values
mixed —__get()
Report that $property doesn't exist.
public
__get(string $property) : mixed
Parameters
- $property : string
Return values
mixed —__set()
Report that $property doesn't exist and set the property to the given $value.
public
__set(string $property, mixed $value) : mixed
Parameters
- $property : string
- $value : mixed
Return values
mixed —__toString()
The object is used as an string.
public
__toString() : string
Return values
string —count()
Returns the number of elements in the collection.
public
count() : int
Tags
Return values
int —find()
Returns the first item that matches the conditions.
public
find(mixed $conditions[, bool $allowNone = false ]) : mixed
Parameters
- $conditions : mixed
-
array|Closure|expression See Collection::where() for condition options
- $allowNone : bool = false
-
When no match is found, return null instead of throwing an Exception.
Return values
mixed —getIterator()
public
getIterator() : Iterator
Return values
Iterator —getQuery()
Inspect the SQL query.
public
getQuery() : string|Sql
Return values
string|Sql —hasEvent()
Check id the $event is a registered event.
public
hasEvent(string $event) : bool
Parameters
- $event : string
Return values
bool —indexOf()
Returns the the key of first item that matches the conditions.
public
indexOf(mixed $conditions) : mixed|null
Returns null when nothing matched the conditions.
Parameters
- $conditions : mixed
-
array|Closure|expression See Collection::where() for condition options
Return values
mixed|null —map()
Creates a new collection with all values converted by the callback.
public
map(mixed $callback) : Collection
Parameters
- $callback : mixed
Tags
Return values
Collection —max()
Return the highest value.
public
max([mixed $selector = '.' ]) : mixed
Parameters
- $selector : mixed = '.'
-
Path to the variable to select. Examples: "->id", "[message]", "customer.name"
Tags
Return values
mixed —min()
Return the lowest value.
public
min([mixed $selector = '.' ]) : mixed
Parameters
- $selector : mixed = '.'
-
Path to the variable to select. Examples: "->id", "[message]", "customer.name"
Tags
Return values
mixed —off()
Remove a callback from an event.
public
off(string $event, string $identifier) : mixed
Parameters
- $event : string
- $identifier : string
Return values
mixed —offsetExists()
Whether a offset exists.
public
offsetExists(int|string $offset) : bool
Parameters
- $offset : int|string
Tags
Return values
bool —offsetGet()
Offset to retrieve.
public
offsetGet(int|string $offset) : mixed
Parameters
- $offset : int|string
Tags
Return values
mixed —offsetSet()
Offset to set.
public
offsetSet(int|string $offset, mixed $value) : mixed
Parameters
- $offset : int|string
- $value : mixed
Tags
Return values
mixed —offsetUnset()
Offset to unset.
public
offsetUnset(mixed $offset) : mixed
Parameters
- $offset : mixed
Tags
Return values
mixed —on()
Add a callback for an event.
public
on(string $event, Closure|string|array<string|int, mixed> $callback) : string
Parameters
- $event : string
- $callback : Closure|string|array<string|int, mixed>
Return values
string —identifier
orderBy()
Return a new collection sorted by the given field in ascending order.
public
orderBy(string $selector[, int $method = SORT_REGULAR ]) : Collection
Parameters
- $selector : string
- $method : int = SORT_REGULAR
-
The sorting method, options are: SORT_REGULAR, SORT_NUMERIC, SORT_STRING or SORT_NATURAL
Return values
Collection —orderByDescending()
Return a new collection sorted by the given field in descending order.
public
orderByDescending(string $selector[, int $method = SORT_REGULAR ]) : Collection
Parameters
- $selector : string
- $method : int = SORT_REGULAR
-
The sorting method, options are: SORT_REGULAR, SORT_NUMERIC, SORT_STRING or SORT_NATURAL
Return values
Collection —reduce()
Iteratively reduce the collection to a single value using a callback function.
public
reduce(Closure $callback[, mixed $initial = null ]) : mixed
Parameters
- $callback : Closure
-
The callback is called per item and the return value is given as result to the next callback.
- $initial : mixed = null
-
The inital value of the result.
Tags
Return values
mixed —remove()
Remove one or more items from the this collection.
public
remove(mixed $conditions[, mixed $allowNone = false ]) : bool
Parameters
- $conditions : mixed
-
array|Closure|expression See Collection::where() for condition options
- $allowNone : mixed = false
Return values
bool —reverse()
Return a new collection in the reverse order.
public
reverse() : Collection
Return values
Collection —select()
Return a new collection where each element is a subselection of the original element.
public
select(string|array<string|int, mixed> $selector[, string|null|false $selectKey = false ]) : Collection
(Known as "collect" in Ruby or "pluck" in underscore.js).
Parameters
- $selector : string|array<string|int, mixed>
-
Path to the variable to select. Examples: "->id", "[message]", "customer.name", array('id' => 'message_id', 'message' => 'message_text')
- $selectKey : string|null|false = false
-
(optional) The path that will be used as key. false: Keep the current key, null: create linear keys.
Return values
Collection —selectKey()
Returns a new collection where the key is based on a property.
public
selectKey(string|null|Closure $selector) : Collection
Parameters
- $selector : string|null|Closure
-
The path that will be used as key.
Return values
Collection —setQuery()
Override the SQL query.
public
setQuery(string|Sql $sql) : mixed
Parameters
- $sql : string|Sql
Return values
mixed —skip()
Return a new Collection without the first x items.
public
skip(int $offset) : Collection
Parameters
- $offset : int
Return values
Collection —take()
Return a new Collection with only the first x items.
public
take(int $limit) : Collection
Parameters
- $limit : int
Return values
Collection —toArray()
Return the collection as an array.
public
toArray() : array<string|int, mixed>
Return values
array<string|int, mixed> —trigger()
Trigger an event.
public
trigger(string $event, stdClass $sender[, mixed $args = null ]) : mixed
Parameters
- $event : string
- $sender : stdClass
- $args : mixed = null
-
(optional)
Return values
mixed —where()
Return a subsection of the collection based on the conditions.
public
where(array<string|int, mixed> $conditions) : Collection
Convert the $conditions to SQL object when appropriate.
auto converts ['x_id' => null] to "x_id IS NULL" ['x_id !=' => null] to "x_id IS NOT NULL" 'hits' => 0] to "hits = '0'" (Because in mysql '' = 0 evaluates to true, '' = '0' to false)
Parameters
- $conditions : array<string|int, mixed>
Return values
Collection —buildFilter()
Build a closure which validates an item with the gives $conditions.
protected
buildFilter(mixed $conditions) : callable
Parameters
- $conditions : mixed
-
array|Closure|expression See Collection::where() for condition options
Return values
callable —dataToArray()
Converts $this->data into an array.
protected
dataToArray() : mixed
Return values
mixed —convertPathToColumn()
Convert a path to a (escaped) columnname.
private
convertPathToColumn(string $path) : mixed
Parameters
- $path : string
Return values
mixed —quote()
Don't put quotes around number for columns that are assumend to be integers ('id' or ending in '_id').
private
quote(Database $db, string $column, mixed $value) : mixed
Parameters
- $db : Database
- $column : string
- $value : mixed