ExpressionEngine Docs

# Collections

- Simple Example
- Method Reference

## 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 EllisLab\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 `EllisLab\ExpressionEngine\Library\Data\Collection`

- `asArray()`
- `first()`
- `last()`
- `pluck($key)`
- `collect($collector)`
- `sortBy($column, $flags = SORT_REGULAR)`
- `reverse()`
- `indexBy($extractor)`
- `getDictionary($key, $value)`
- `map($callback)`
- `filter($callback)`
- `each($callback)`
- `count()`

### `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`
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`
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`
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

### `count()`

Count the elements in the Collection

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