ExpressionEngine Docs

Collections

Simple Example

The collection class is a list-style container for composite datatypes that adds more utility than storing them in a simple PHP array. It can store both arrays and objects:

use ExpressionEngine\Library\Data\Collection;

$collection = new Collection(array(
  array('name' => 'Anne', 'age' => 47),
  array('name' => 'Bob', 'age' => 32),
  array('name' => 'Julie', 'age' => 14),
  array('name' => 'Jack', 'age' => 86)
));

$collection->count(); // 4
$collection->first(); // Anne's array

$sorted = $collection->sortBy('age');
$sorted->first(); // Julie's array

For basic interactions a collection can be treated as a regular array:

foreach ($collection as $person)
{
  echo $person['age']; // or $person->age if your collection contains objects
}

$collection[] = array('name' => 'Savannah', 27);

Note: Indices are always uninterrupted numeric sequences starting at 0. Do not use string keys.

Method Reference

class ExpressionEngine\Library\Data\Collection

asArray()

Turn the collection into an array

Parameter Type Description
Returns Array The collection items

first()

Get the first element in the collection

Parameter Type Description
Returns Mixed The first element in the collection (or NULL if empty)

last()

Get the last element in the collection

Parameter Type Description
Returns Mixed The last element in the collection (or NULL if empty)

pluck($key)

Extract a value from all elements of the collection

Parameter Type Description
$key String The key or property name to pluck
Returns Array Array of values for the key

collect($collector)

Extract a value from all elements of the collection using a keyname or callback.

Parameter Type Description
$extractor String|Closure The name of the property or a closure that returns a value for an item.
Returns Array Array of values for the key

sortBy($column, $flags = SORT_REGULAR)

Sort a collection by a certain element key. Returns a new collection.

Parameter Type Description
$key String The key or property to sort by
$flags Int A PHP sort flag
Returns Collection A new collection

reverse()

Reverse the elements in the collection. Returns a new collection.

Parameter Type Description
Returns Collection A new collection with the elements in reverse

indexBy($extractor)

Return an associative array of all items indexed by a given element.

It is up to you to ensure that the index keys are unique. If $extractor is a closure it will be passed each element in the collection and should return the value to use.

Parameter Type Description
$extractor String|Closure The name of the property or a closure that returns a value for an item.
Returns Array Associative array of elements

getDictionary($key, $value)

Return a key-value array composed of two items in each collection element.

It is up to you to ensure that the index keys are unique.

Parameter Type Description
$extractor String|Closure The name of the property or a closure that returns a value for an item.
Returns Array Associative key-value array

map($callback)

Applies the given callback to the collection and returns an array of the results.

Parameter Type Description
$key String The name of the property
Returns Array The value of the property

filter($callback)

Filter elements of a collection using a callback function. If the callback returns TRUE the current value from the collection is returned in the result Collection.

Parameter Type Description
$callback Closure The callback function to use
Returns Collection New collection of filtered elements.

each($callback)

Iterates over all the elements in the Collection and passes them to them to the Callback one at a time.

Parameter Type Description
$callback Closure The callback to pass each element to
Returns Collection The original collection

removeElement($model)

Removes an element from the Collection and returns the reduced Collection.

Parameter Type Description
$model Model An instance of the Model element held in the collection.
Returns Collection The updated collection without the $model element (if found).

Note: This is a handy way to correct for an issue with the EE Model search method which performs %search_term% searches rather than literal searches, so you get back all the records that contain the search term in the nominated field rather than those that match the search term. For example, if $collection is a Collection object, this code removes any elements that fail to meet a conditional test - so if it had 100 elements to begin with and 5 fail the test, after the code $collection->count() will return 95:

foreach($collection as $element) {
    if($element->field != 'reference_value') {
        $collection->removeElement($element);
    }
}

count()

Count the elements in the Collection

Parameter Type Description
Returns Int The number of items in the Collection