API Documentation
\
Charcoal
Loader
Model
Service
ServiceProvider
Source
Database
Validator

\Charcoal\ModelCollection

A Model Collection

For iterating instances of \Charcoal\Model\ModelInterface.

Used by \Charcoal\Loader\CollectionLoader for storing results.

The collection stores models by their primary key. If two objects share the same storable ID but hold disparate data, they are considered to be alike. Adding an object that shares the same ID as an object previously stored in the collection will replace the latter.

Summary

Methods
Properties
Constants
__construct()
first()
last()
merge()
add()
get()
has()
remove()
clear()
all()
values()
keys()
offsetExists()
offsetGet()
offsetSet()
offsetUnset()
count()
getIterator()
getCachingIterator()
pos()
objects()
map()
isAcceptable()
isEmpty()
toBase()
No public properties found
No constants found
resolveOffset()
modelKey()
asArray()
$objects
N/A
No private methods found
No private properties found
N/A

Properties

$objects

$objects : array<mixed,object>

The objects contained in the collection.

Stored as a dictionary indexed by each object's primary key. Ensures that each object gets loaded only once by keeping every loaded object in an associative array.

Type

array<mixed,object>

Methods

__construct()

__construct(array|\Traversable|null  $objs = null) : void

Create a new collection.

Parameters

array|\Traversable|null $objs

Array of objects to pre-populate this collection.

first()

first() : object|null

Retrieve the first object in the collection.

Returns

object|null —

Returns the first object, or NULL if the collection is empty.

last()

last() : object|null

Retrieve the last object in the collection.

Returns

object|null —

Returns the last object, or NULL if the collection is empty.

merge()

merge(array|\Traversable  $objs) : self

Merge the collection with the given objects.

Parameters

array|\Traversable $objs

Array of objects to append to this collection.

Throws

\InvalidArgumentException

If the given array contains an unacceptable value.

Returns

self

add()

add(object  $obj) : self

Add an object to the collection.

Parameters

object $obj

An acceptable object.

Throws

\InvalidArgumentException

If the given object is not acceptable.

Returns

self

get()

get(mixed  $key) : object|null

Retrieve the object by primary key.

Parameters

mixed $key

The primary key.

Returns

object|null —

Returns the requested object or NULL if not in the collection.

has()

has(mixed  $key) : boolean

Determine if an object exists in the collection by key.

Parameters

mixed $key

The primary key to lookup.

Returns

boolean

remove()

remove(mixed  $key) : self

Remove object from collection by primary key.

Parameters

mixed $key

The object primary key to remove.

Throws

\InvalidArgumentException

If the given key is not acceptable.

Returns

self

clear()

clear() : self

Remove all objects from collection.

Returns

self

all()

all() : array<mixed,object>

Retrieve all objects in collection indexed by primary keys.

Returns

array<mixed,object> —

An associative array of objects.

values()

values() : array<mixed,object>

Retrieve all objects in the collection indexed numerically.

Returns

array<mixed,object> —

A sequential array of objects.

keys()

keys() : array

Retrieve the primary keys of the objects in the collection.

Returns

array —

A sequential array of keys.

offsetExists()

offsetExists(mixed  $offset) : boolean

Alias of {@see CollectionInterface::has()}.

Parameters

mixed $offset

The object primary key or array offset.

Returns

boolean

offsetGet()

offsetGet(mixed  $offset) : mixed

Alias of {@see CollectionInterface::get()}.

Parameters

mixed $offset

The object primary key or array offset.

Returns

mixed —

Returns the requested object or NULL if not in the collection.

offsetSet()

offsetSet(mixed  $offset, mixed  $value) : void

Alias of {@see CollectionInterface::set()}.

Parameters

mixed $offset

The object primary key or array offset.
mixed $value

The object.

Throws

\LogicException

Attempts to assign an offset.

offsetUnset()

offsetUnset(mixed  $offset) : void

Alias of {@see CollectionInterface::remove()}.

Parameters

mixed $offset

The object primary key or array offset.

count()

count() : integer

Get number of objects in collection

Returns

integer

getIterator()

getIterator() : \ArrayIterator

Retrieve an external iterator.

Returns

\ArrayIterator

getCachingIterator()

getCachingIterator(integer  $flags = \CachingIterator::CALL_TOSTRING) : \CachingIterator

Retrieve a cached iterator.

Parameters

integer $flags

Bitmask of flags.

Returns

\CachingIterator

pos()

pos(mixed  $key) : integer

Retrieve the array offset from the given key.

Parameters

mixed $key

The primary key to retrieve the offset from.

Returns

integer —

Returns an array offset.

objects()

objects() : array<mixed,object>

Alias of {@see self::values()}

Returns

array<mixed,object>

map()

map() : array<mixed,object>

Alias of {@see self::all()}.

Returns

array<mixed,object>

isAcceptable()

isAcceptable(mixed  $value) : boolean

Determine if the given value is acceptable for the collection.

Note: Practical for specialized collections extending the base collection.

Parameters

mixed $value

The value being vetted.

Returns

boolean

isEmpty()

isEmpty() : boolean

Determine if the collection is empty or not.

Returns

boolean

toBase()

toBase() : \Charcoal\Model\Collection

Get a base collection instance from this collection.

Note: Practical for extended classes.

Returns

\Charcoal\Model\Collection

resolveOffset()

resolveOffset(integer  $offset) : integer

Parse the array offset.

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

Parameters

integer $offset

The array offset.

Returns

integer —

Returns the resolved array offset.

modelKey()

modelKey(object  $obj) : boolean

Convert a given object into a model identifier.

Note: Practical for specialized collections extending the base collection.

Parameters

object $obj

An acceptable object.

Throws

\InvalidArgumentException

If the given object is not acceptable.

Returns

boolean

asArray()

asArray(mixed  $value) : array

Parse the given value into an array.

Parameters

mixed $value

The value being converted.

Returns

array