Getting Started

Introduction

Doctrine Collections is a library that contains classes for working with arrays of data. Here is an example using the simple Doctrine\Common\Collections\ArrayCollection class:

1 <?php

use Doctrine\Common\Collections\ArrayCollection;

$collection = new ArrayCollection([1, 2, 3]);

$filteredCollection = $collection->filter(function($element) {
    return $element > 1;
}); // [2, 3]
2
3
4
5
6
7
8
9

Doctrine Collections provides an interface named Doctrine\Common\Collections\Collection that resembles the nature of a regular PHP array. That is, it is essentially an ordered map that can also be used like a list.

A Collection has an internal iterator just like a PHP array. In addition, a Collection can be iterated with external iterators, which is preferable. To use an external iterator simply use the foreach language construct to iterate over the collection, which calls getIterator() internally, or explicitly retrieve an iterator though getIterator() which can then be used to iterate over the collection. You can not rely on the internal iterator of the collection being at a certain position unless you explicitly positioned it before.

Methods that do not alter the collection or have template types appearing in invariant or contravariant positions are not directly defined in Doctrine\Common\Collections\Collection, but are inherited from the Doctrine\Common\Collections\ReadableCollection interface.

The methods available on the interface are:

add

Adds an element at the end of the collection.

1 $collection->add('test');

clear

Clears the collection, removing all elements.

1 $collection->clear();

contains

Checks whether an element is contained in the collection. This is an O(n) operation, where n is the size of the collection.

1 $collection = new Collection(['test']);

$contains = $collection->contains('test'); // true
2
3

containsKey

Checks whether the collection contains an element with the specified key/index.

1 $collection = new Collection(['test' => true]);

$contains = $collection->containsKey('test'); // true
2
3

current

Gets the element of the collection at the current iterator position.

1 $collection = new Collection(['first', 'second', 'third']);

$current = $collection->current(); // first
2
3

get

Gets the element at the specified key/index.

1 $collection = new Collection([
    'key' => 'value',
]);

$value = $collection->get('key'); // value
2
3
4
5

getKeys

Gets all keys/indices of the collection.

1 $collection = new Collection(['a', 'b', 'c']);

$keys = $collection->getKeys(); // [0, 1, 2]
2
3

getValues

Gets all values of the collection.

1 $collection = new Collection([
    'key1' => 'value1',
    'key2' => 'value2',
    'key3' => 'value3',
]);

$values = $collection->getValues(); // ['value1', 'value2', 'value3']
2
3
4
5
6
7

isEmpty

Checks whether the collection is empty (contains no elements).

1 $collection = new Collection(['a', 'b', 'c']);

$isEmpty = $collection->isEmpty(); // false
2
3

first

Sets the internal iterator to the first element in the collection and returns this element.

1 $collection = new Collection(['first', 'second', 'third']);

$first = $collection->first(); // first
2
3

exists

Tests for the existence of an element that satisfies the given predicate.

1 $collection = new Collection(['first', 'second', 'third']);

$exists = $collection->exists(function($key, $value) {
    return $value === 'first';
}); // true
2
3
4
5

findFirst

Returns the first element of this collection that satisfies the given predicate.

1 $collection = new Collection([1, 2, 3, 2, 1]);

$one = $collection->findFirst(function(int $key, int $value): bool {
    return $value > 2 && $key > 1;
}); // 3
2
3
4
5

filter

Returns all the elements of this collection for which your callback function returns true. The order and keys of the elements are preserved.

1 $collection = new ArrayCollection([1, 2, 3]);

$filteredCollection = $collection->filter(function($element) {
    return $element > 1;
}); // [2, 3]
2
3
4
5

forAll

Tests whether the given predicate holds for all elements of this collection.

1 $collection = new ArrayCollection([1, 2, 3]);

$forAll = $collection->forAll(function($key, $value) {
    return $value > 1;
}); // false
2
3
4
5

indexOf

Gets the index/key of a given element. The comparison of two elements is strict, that means not only the value but also the type must match. For objects this means reference equality.

1 $collection = new ArrayCollection([1, 2, 3]);

$indexOf = $collection->indexOf(3); // 2
2
3

key

Gets the key/index of the element at the current iterator position.

1 $collection = new ArrayCollection([1, 2, 3]);

$collection->next();

$key = $collection->key(); // 1
2
3
4
5

last

Sets the internal iterator to the last element in the collection and returns this element.

1 $collection = new ArrayCollection([1, 2, 3]);

$last = $collection->last(); // 3
2
3

map

Applies the given function to each element in the collection and returns a new collection with the elements returned by the function.

1 $collection = new ArrayCollection([1, 2, 3]);

$mappedCollection = $collection->map(function($value) {
    return $value + 1;
}); // [2, 3, 4]
2
3
4
5

reduce

Applies iteratively the given function to each element in the collection, so as to reduce the collection to a single value.

1 $collection = new ArrayCollection([1, 2, 3]);

$reduce = $collection->reduce(function(int $accumulator, int $value): int {
    return $accumulator + $value;
}, 0); // 6
2
3
4
5

Moves the internal iterator position to the next element and returns this element.

1 $collection = new ArrayCollection([1, 2, 3]);

$next = $collection->next(); // 2
2
3

partition

Partitions this collection in two collections according to a predicate. Keys are preserved in the resulting collections.

1 $collection = new ArrayCollection([1, 2, 3]);

$mappedCollection = $collection->partition(function($key, $value) {
    return $value > 1
}); // [[2, 3], [1]]
2
3
4
5

remove

Removes the element at the specified index from the collection.

1 $collection = new ArrayCollection([1, 2, 3]);

$collection->remove(0); // [2, 3]
2
3

removeElement

Removes the specified element from the collection, if it is found.

1 $collection = new ArrayCollection([1, 2, 3]);

$collection->removeElement(3); // [1, 2]
2
3

set

Sets an element in the collection at the specified key/index.

1 $collection = new ArrayCollection();

$collection->set('name', 'jwage');
2
3

slice

Extracts a slice of $length elements starting at position $offset from the Collection. If $length is null it returns all elements from $offset to the end of the Collection. Keys have to be preserved by this method. Calling this method will only return the selected slice and NOT change the elements contained in the collection slice is called on.

1 $collection = new ArrayCollection([0, 1, 2, 3, 4, 5]);

$slice = $collection->slice(1, 2); // [1, 2]
2
3

toArray

Gets a native PHP array representation of the collection.

1 $collection = new ArrayCollection([0, 1, 2, 3, 4, 5]);

$array = $collection->toArray(); // [0, 1, 2, 3, 4, 5]
2
3

Selectable Methods

Some Doctrine Collections, like Doctrine\Common\Collections\ArrayCollection, implement an interface named Doctrine\Common\Collections\Selectable that offers the usage of a powerful expressions API, where conditions can be applied to a collection to get a result with matching elements only.

matching

Selects all elements from a selectable that match the expression and returns a new collection containing these elements and preserved keys.

1 use Doctrine\Common\Collections\Criteria;
use Doctrine\Common\Collections\Expr\Comparison;

$collection = new ArrayCollection([
    'wage' => [
        'name' => 'jwage',
    ],
    'roman' => [
        'name' => 'romanb',
    ],
]);

$expr = new Comparison('name', '=', 'jwage');

$criteria = new Criteria();

$criteria->where($expr);

$matchingCollection = $collection->matching($criteria); // [ 'wage' => [ 'name' => 'jwage' ]]
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

You can read more about expressions here.

1	<?php use Doctrine\Common\Collections\ArrayCollection; $collection = new ArrayCollection([1, 2, 3]); $filteredCollection = $collection->filter(function($element) { return $element > 1; }); // [2, 3]
2
3
4
5
6
7
8
9

1	$collection = new Collection(['test']); $contains = $collection->contains('test'); // true
2
3

1	$collection = new Collection(['test' => true]); $contains = $collection->containsKey('test'); // true
2
3

1	$collection = new Collection(['first', 'second', 'third']); $current = $collection->current(); // first
2
3

1	$collection = new Collection([ 'key' => 'value', ]); $value = $collection->get('key'); // value
2
3
4
5

1	$collection = new Collection(['a', 'b', 'c']); $keys = $collection->getKeys(); // [0, 1, 2]
2
3

1	$collection = new Collection([ 'key1' => 'value1', 'key2' => 'value2', 'key3' => 'value3', ]); $values = $collection->getValues(); // ['value1', 'value2', 'value3']
2
3
4
5
6
7

1	$collection = new Collection([1, 2, 3, 2, 1]); $one = $collection->findFirst(function(int $key, int $value): bool { return $value > 2 && $key > 1; }); // 3
2
3
4
5

1	$collection = new ArrayCollection([1, 2, 3]); $filteredCollection = $collection->filter(function($element) { return $element > 1; }); // [2, 3]
2
3
4
5

1	$collection = new ArrayCollection(); $collection->set('name', 'jwage');
2
3

1	$collection = new ArrayCollection([0, 1, 2, 3, 4, 5]); $slice = $collection->slice(1, 2); // [1, 2]
2
3

1	use Doctrine\Common\Collections\Criteria; use Doctrine\Common\Collections\Expr\Comparison; $collection = new ArrayCollection([ 'wage' => [ 'name' => 'jwage', ], 'roman' => [ 'name' => 'romanb', ], ]); $expr = new Comparison('name', '=', 'jwage'); $criteria = new Criteria(); $criteria->where($expr); $matchingCollection = $collection->matching($criteria); // [ 'wage' => [ 'name' => 'jwage' ]]
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

Maintained

Unmaintained