The primary purpose of this class is to keep a number of Datarecords bundled together. In addition to convenience, this can also speed things up when using the reference-fields in the Datarecord class as information for all contained Datarecord objects can be queried at the same time.

Usually the Collection is the result of using the Filter object, but it can be spawned on its own, passing a Datarecord or an array of Datarecords into the constructor, or adding it later using the add function.

$collection = new Collection($user);
$collection->add($another_user);

A datarecord can only contain objects of the same type and will adapt to the first object it receives.

The collection can be sorted by a specific field using sort and implements the PHP Iterator interface, so it can be used like any iterator:

$collection->sort('full_name');
foreach ($collection as $user) {
    echo $user->full_name;
}

There are also some more sofisticated get-functions such as getting the value of a single field from the objects in the collection

foreach ($collection->getAllFullValues('full_name') as $value) {
   echo $value;
}