class ModelCollection implements ArrayAccess, IteratorAggregate, Countable mixin ScopesTrait

Constants

SORT_ALPHABETICAL

SORT_NUMERICAL

SORT_ASC

SORT_DESC

EVENT_AFTER_LOAD

Properties

protected Model $model

reference to model-type

protected bool|Model[] $models

Array of models in this collection

protected bool $loaded

Boolean which indicates whether collection is loaded or not (not equal empty!)

bool $canBeScoped

ModelCollection cannot be scoped anymore if manual changes have been made

Methods

mixed
__call(mixed $method, mixed $args = array())

Handle find functions

__clone()

Called after cloning a collection and makes sure that model reference is cloned as well

__construct(Model $model, array|ModelCollection $model_array = null, bool $useModelClone = true)

Create new Model Array

__toString()

No description

_search_by(string $query, array|bool $parameters = false, bool $return_single = true)

returns model found by property => value

add_formatted_property(string $property, string $format, array $options = array())

Apply lib->format multi_format on passed property. The result will be written to ->[property]_formatted

all(array $args = array())

Find Function to find models using the passed condition

void
append(Model $model)

Adds an Object to the models-array.

attach(string $property, array $values, string $key_field = null)

Set property values to models from array

batchProcess(int $batchSize, callable $callback)

Runs the passed function batched for the passed amount of models to reduce memory issues while creating too many model objects at once This function should be called on an unloaded Collection to be most effective This method is ignoring any limits which might have been set on the scopeQuery!

int
count()

Returns the number of containing models Attention: This will load all models of the collection Use $model_collection->count_all() for this case to determine count without loading all models Note: this function is called if the php function count(this_collection) is used

int
countAll()

Return the maximum number of items in this collection, will return the count of all items in the database if the collection is a scoped collection and ignore limits set. Will return local count for manual collections

int
count_all() deprecated

No description

array
debug()

Use for debugging

void
filter(mixed $callback = false)

DESTRUCTIVE This will manipulate the models-list and doesn't return anything!

Model|null
first()

Get first model of collection, without shifting

getDocumentIndexes()

Prefetch and returns document index objects for all items of this collection.

T>
getIterator()

foreach($collection) .

getRelatedDocumentIndexCollection()

Returns a DocumentIndexCollection which is NOT loaded

array|bool
get_db_properties()

No description

get_model()

Returns the Default-Model (-Type) for this Collection

string
get_model_class()

put your comment there.

array|Model[]
get_models()

Returns array with objects

array
invoke(string $method)

Calls the passed method for each object

bool
isScopeable()

Returns true if the collection has no manual modifications yet

bool
is_loaded()

Returns true if this collection has been filled

Model|null
last()

Return the last element of the collection, not popping

limit(int $limit, int $offset = 0)

Limit the visible articles.

void
merge()

DESTRUCTIVE This will manipulate the models-list and doesn't return anything!

bool
offsetExists(mixed $offset)

isset($collection[0])

offsetGet(mixed $offset)

$collection[0]

offsetSet(mixed $offset, mixed $value)

$collections[0] = $entry

offsetUnset(mixed $offset)

unset($collection[0])

orderBy(string $field, string $sortDirection = ModelCollection::SORT_ASC)

No description

pluck(string|string[] $property, string $key_field = null)

Returns the passed property of all objects in an array

array
pluckWithScopeQuery(string $property, string|null $key_field = null)

Returns the passed property. In contrast to pluck() this function does not use the loaded models but uses a SQL query to retrieve the values Attention: This returns the RAW database values

array
pluck_unique(mixed $property, mixed $key_field = false)

Returns the passed property of all objects in an array (unique and filtered)

Model|null
pop()

this function returns the last value of the models-array, shortening the models-array by one element.

int
push(Model ...$models)

this function treats models-array as a stack, and pushes the passed variables onto the end of array.

bool
require_loading()

If the collection is not loaded yet the collection will use all() to be filled

reset()

Resets the loaded collection by clearing all loaded models and marking the collection as not being loaded.

reverse(bool $preserve_keys = false)

DESTRUCTIVE This will manipulate the models-list and doesn't return anything!

save(bool $silent = false)

No description

scope_by_COL(mixed $value)

No description

Model[]
search_all_by_id(mixed $id, mixed $query_params)

No description

Model|null
search_by_id(mixed $id, mixed $query_params)

No description

setCanBeScoped(bool $canBeScoped = true)

No description

setEmpty()

Set this ModelCollection as loaded and empty collection

setModels(Model[]|ModelCollection $models)

Setting model manually in a collection will set the collection prefilled/not scopable

setProperty(string $key, mixed $value)

No description

Model|null
shift()

This function shifts the first value of the models-array off and returns it, shortening the array by one element and moving everything down.

slice(int $offset, int|bool $length = false, bool $preserve_keys = false) deprecated

DESTRUCTIVE This will manipulate the models-list and doesn't return anything!

sortByQuery(Query $query = null)

Mimics the SQL sorting on the ModelCollection

sort_by(string $property, string $order_by = 'asc') deprecated

Sorts the current Collection by given Property-Name

mixed
sum(string $property, string|bool $group_field = false)

Returns the sum of the passed property across all models

array|Model[]
to_array(bool $raw = false)

Returns collection as array of models

string
to_json()

Returns collection as json of models

string
to_string()

Returns collection as string

string
to_xml(array|bool $property_filter = false)

Returns an XML of all model properties

int
unshift()

This function prepends passed elements to the front of the array.

bool
usort(callable $cmp_function)

DESTRUCTIVE This will manipulate the models-list and doesn't return anything!

Details

at line 254
mixed __call(mixed $method, mixed $args = array())

Handle find functions

Parameters

mixed $method
mixed $args

Return Value

mixed

at line 1507
__clone()

Called after cloning a collection and makes sure that model reference is cloned as well

at line 101
__construct(Model $model, array|ModelCollection $model_array = null, bool $useModelClone = true)

Create new Model Array

Parameters

Model $model

Reference to Model

array|ModelCollection $model_array

Optional array of Models to initialize collection with

bool $useModelClone

at line 967
__toString()

No description

at line 666
protected Model|ModelCollection|null _search_by(string $query, array|bool $parameters = false, bool $return_single = true)

returns model found by property => value

Parameters

string $query

function_name_query (e.g.: title_and_user_id)

array|bool $parameters
bool $return_single

determines the result-type [FALSE] : Model or boolean false on fail [TRUE] : ModelCollection

Return Value

Model|ModelCollection|null

see also param-doc of "$return_single"

at line 954
add_formatted_property(string $property, string $format, array $options = array())

Apply lib->format multi_format on passed property. The result will be written to ->[property]_formatted

Parameters

string $property

Property of models to format

string $format

Format Type (e.g. money, date, ...)

array $options

Additional format options

at line 371
ModelCollection all(array $args = array())

Find Function to find models using the passed condition

Parameters

array $args

Further query parameters (e.g. LIMIT) $params['limit'] --> Limit condition, e.g. limit=>'1,10' $params['order_by'] --> Order condition, e.g. order_by='id ASC'

Return Value

ModelCollection result

at line 1049
void append(Model $model)

Adds an Object to the models-array.

It will be appended after the last position of array

Parameters

Model $model

Return Value

void

at line 631
attach(string $property, array $values, string $key_field = null)

Set property values to models from array

Parameters

string $property

e.g. calculated_property

array $values

['id1'=>'CALCULATED for id1']

string $key_field

Will default to table_primary_key

at line 483
batchProcess(int $batchSize, callable $callback)

Runs the passed function batched for the passed amount of models to reduce memory issues while creating too many model objects at once This function should be called on an unloaded Collection to be most effective This method is ignoring any limits which might have been set on the scopeQuery!

Parameters

int $batchSize

Number of models which should be processed per chunk

callable $callback

Callback which will be called for each chunk. The function receives a ModelCollection as the first argument which contains a subset of models for this chunk run.

at line 1028
int count()

Returns the number of containing models Attention: This will load all models of the collection Use $model_collection->count_all() for this case to determine count without loading all models Note: this function is called if the php function count(this_collection) is used

Return Value

int

count of models

at line 1543
int countAll()

Return the maximum number of items in this collection, will return the count of all items in the database if the collection is a scoped collection and ignore limits set. Will return local count for manual collections

Return Value

int

at line 1555
int count_all() deprecated

deprecated Use countAll()

No description

Return Value

int

at line 1416
array debug()

Use for debugging

Return Value

array

at line 1195
void filter(mixed $callback = false)

DESTRUCTIVE This will manipulate the models-list and doesn't return anything!

Iterates over each value in the models-array passing them to the callback function. If the callback function returns true, the current value from input is returned into the result array. Array keys are preserved.

Parameters

mixed $callback

If the callback function is not supplied, array_filter() will remove all the entries of input that are equal to FALSE, null or ''

Return Value

void

at line 1260
Model|null first()

Get first model of collection, without shifting

Return Value

Model|null

at line 195
DocumentIndexCollection getDocumentIndexes()

Prefetch and returns document index objects for all items of this collection.

at line 1492
T> getIterator()

foreach($collection) .

..

Return Value

T>

at line 219
DocumentIndexCollection getRelatedDocumentIndexCollection()

Returns a DocumentIndexCollection which is NOT loaded

at line 1404
array|bool get_db_properties()

No description

Return Value

array|bool

at line 1397
Model get_model()

Returns the Default-Model (-Type) for this Collection

Return Value

Model

at line 120
string get_model_class()

put your comment there.

..

Return Value

string ???

at line 128
array|Model[] get_models()

Returns array with objects

Return Value

array|Model[]

at line 460
array invoke(string $method)

internal  param mixed $args Additional Parameters
 

Calls the passed method for each object

Parameters

string $method

Method Name

Return Value

array

[like pluck]

at line 1535
bool isScopeable()

Returns true if the collection has no manual modifications yet

Return Value

bool

at line 136
bool is_loaded()

Returns true if this collection has been filled

Return Value

bool

True if loaded

at line 1251
Model|null last()

Return the last element of the collection, not popping

Return Value

Model|null

at line 1273
final ModelCollection limit(int $limit, int $offset = 0)

Limit the visible articles.

Parameters

int $limit
int $offset

Return Value

ModelCollection

at line 1096
void merge()

DESTRUCTIVE This will manipulate the models-list and doesn't return anything!

Merges the elements of one or more arrays together so that the values of one are appended to the end of the previous one. It returns the resulting array. If the input arrays have the same string keys, then the later value for that key will overwrite the previous one. If, however, the arrays contain numeric keys, the later value will not overwrite the original value, but will be appended. If only one array is given and the array is numerically indexed, the keys get reindexed in a continuous way.

Return Value

void

at line 1456
bool offsetExists(mixed $offset)

isset($collection[0])

Parameters

mixed $offset

Return Value

bool

at line 1480
Model offsetGet(mixed $offset)

$collection[0]

Parameters

mixed $offset

Return Value

Model

at line 1439
offsetSet(mixed $offset, mixed $value)

$collections[0] = $entry

Parameters

mixed $offset
mixed $value

at line 1467
offsetUnset(mixed $offset)

unset($collection[0])

Parameters

mixed $offset

at line 1289
final ModelCollection orderBy(string $field, string $sortDirection = ModelCollection::SORT_ASC)

No description

Parameters

string $field
string $sortDirection

Return Value

ModelCollection

at line 543
pluck(string|string[] $property, string $key_field = null)

Returns the passed property of all objects in an array

Parameters

string|string[] $property

[array ior], pass * to retrieve all properties, pass 'this' to retrieve models

string $key_field

at line 612
array pluckWithScopeQuery(string $property, string|null $key_field = null)

Returns the passed property. In contrast to pluck() this function does not use the loaded models but uses a SQL query to retrieve the values Attention: This returns the RAW database values

Parameters

string $property
string|null $key_field

Return Value

array

at line 594
array pluck_unique(mixed $property, mixed $key_field = false)

Returns the passed property of all objects in an array (unique and filtered)

Parameters

mixed $property
mixed $key_field

Return Value

array

at line 1062
Model|null pop()

this function returns the last value of the models-array, shortening the models-array by one element.

Will additionally produce a Warning when called on a non-array.

Return Value

Model|null

Model or NULL if models-array is empty or not an array

at line 1075
int push(Model ...$models)

this function treats models-array as a stack, and pushes the passed variables onto the end of array.

The length of array increases by the number of variables pushed.

Parameters

Model ...$models

Return Value

int

Count of Models after pushing-operation

at line 182
bool require_loading()

If the collection is not loaded yet the collection will use all() to be filled

Return Value

bool

requires loading

at line 1214
reset()

Resets the loaded collection by clearing all loaded models and marking the collection as not being loaded.

Will not reset scope.

at line 1157
reverse(bool $preserve_keys = false)

DESTRUCTIVE This will manipulate the models-list and doesn't return anything!

The models-array will be modified with the order of the elements reversed.

Parameters

bool $preserve_keys

at line 426
ModelCollection save(bool $silent = false)

No description

Parameters

bool $silent

Return Value

ModelCollection

at line 27
ModelCollection scope_by_COL(mixed $value)

No description

Parameters

mixed $value

Return Value

ModelCollection

at line 27
Model[] search_all_by_id(mixed $id, mixed $query_params)

No description

Parameters

mixed $id
mixed $query_params

Return Value

Model[]

at line 27
Model|null search_by_id(mixed $id, mixed $query_params)

No description

Parameters

mixed $id
mixed $query_params

Return Value

Model|null

at line 1526
ModelCollection setCanBeScoped(bool $canBeScoped = true)

No description

Parameters

bool $canBeScoped

Return Value

ModelCollection

at line 171
ModelCollection setEmpty()

Set this ModelCollection as loaded and empty collection

Return Value

ModelCollection

at line 148
ModelCollection setModels(Model[]|ModelCollection $models)

Setting model manually in a collection will set the collection prefilled/not scopable

Parameters

Model[]|ModelCollection $models

Return Value

ModelCollection

at line 408
ModelCollection setProperty(string $key, mixed $value)

No description

Parameters

string $key
mixed $value

Return Value

ModelCollection

at line 1123
Model|null shift()

This function shifts the first value of the models-array off and returns it, shortening the array by one element and moving everything down.

All numerical array keys will be modified to start counting from zero while literal keys won't be touched.

Return Value

Model|null

Returns the shifted value, or NULL if models-array is empty or is not an array.

at line 1241
slice(int $offset, int|bool $length = false, bool $preserve_keys = false) deprecated

deprecated This function should be protected - use limit() instead

DESTRUCTIVE This will manipulate the models-list and doesn't return anything!

Parameters

int $offset

If offset is non-negative, the sequence will start at that offset in the array . If offset is negative, the sequence will start that far from the end of the array .

int|bool $length

If length is given and is positive, then the sequence will have that many elements in it. If length is given and is negative then the sequence will stop that many elements from the end of the array. If it is omitted, then the sequence will have everything from offset up until the end of the array .

bool $preserve_keys

Note that array_slice() will reorder and reset the array indices by default. You can change this behaviour by setting preserve_keys to TRUE.

at line 1340
ModelCollection sortByQuery(Query $query = null)

Mimics the SQL sorting on the ModelCollection

Parameters

Query $query

Return Value

ModelCollection

at line 1322
ModelCollection sort_by(string $property, string $order_by = 'asc') deprecated

deprecated This function should be private and orderBy or sortByQuery should be used as public method (same as slice/limit)

Sorts the current Collection by given Property-Name

Parameters

string $property

Field-Name of the Model-Property (e.g.: 'id', 'created_at', ...)

string $order_by

sort-direction ['asc' | 'desc']

Return Value

ModelCollection

at line 520
mixed sum(string $property, string|bool $group_field = false)

Returns the sum of the passed property across all models

Parameters

string $property

Property Field to sum up (e.g. price)

string|bool $group_field

Optional Group Field to group sums

Return Value

mixed

Returns array or value

at line 978
array|Model[] to_array(bool $raw = false)

Returns collection as array of models

Parameters

bool $raw

If true calls get_properties on each model

Return Value

array|Model[]

at line 995
string to_json()

Returns collection as json of models

Return Value

string

at line 963
string to_string()

Returns collection as string

Return Value

string

at line 1005
string to_xml(array|bool $property_filter = false)

Returns an XML of all model properties

Parameters

array|bool $property_filter

property_filter array if given, only the properties in this array are added

Return Value

string

at line 1136
int unshift()

This function prepends passed elements to the front of the array.

Note that the list of elements is prepended as a whole, so that the prepended elements stay in the same order. All numerical array keys will be modified to start counting from zero while literal keys won't be touched.

Return Value

int

Returns the new number of elements in the array.

at line 443
ModelCollection updateDocumentIndexes()

No description

Return Value

ModelCollection

at line 1179
bool usort(callable $cmp_function)

DESTRUCTIVE This will manipulate the models-list and doesn't return anything!

This function will sort the models-array by its values using a user-supplied comparison function. If the array you wish to sort needs to be sorted by some non-trivial criteria, you should use this function.

Parameters

callable $cmp_function

The comparison function must return an integer less than, equal to, or greater than zero if the first argument is considered to be respectively less than, equal to, or greater than the second.

Return Value

bool

was sorting successful?

Examples

$collection->usort("compare_objects");
$collection->usort(array(&$article, "compare_articles"));