This section describes a few elements which are at the core of Collection and guides on how to get the most out of the package.


Most operations return a new collection object rather than modifying the original one.

Immutability usually makes our code:

  • simpler to use, reason about, and test

  • easier to debug

  • more robust and consistent

A few notable exceptions to this are methods that return scalar values like count; read more about them in the operations background section.


While PHP’s default evaluation is call-by-value, Collection allows you to mimic a call-by-name evaluation strategy by evaluating items only when they are needed.

Therefore, Collection is “lazy” by default. Lazy evaluation is an evaluation strategy which delays the evaluation of an expression until its value is really needed.

Collection operations are executed on the input stream only when iterating over it, or when using very specific operations like all or squash.


Collection leverages PHP Generators and Closures to allow working with large data sets while using as little memory as possible. Thanks to lazy evaluation, we can even deal with potentially infinite data sets or streams of data - see the advanced usage section for more examples.

$even = static fn(int $item): bool => $item % 2 === 0;
$square = static fn(int $item): int => $item * $item;

$collection = Collection::fromIterable(range(0, 5))
    ->map($square); // $collection is still unchanged up to this point

// We can use `all` to get the results as an array
var_dump($collection->all()); // [0, 4, 16]

// Even better, we can iterate over the collection directly
foreach ($collection as $item) {
    var_dump($item); // will print 0, 4, 16


The Collection object is assisted by a couple of powerful components:

ClosureIterator - allows iterating over the collection object by creating a new PHP Generator each time iteration is started.

AbstractOperation and the Operation Interface - provide the blueprint for collection operations, which are pure functions defined as final classes with the invoke PHP magic method. Operations return a Closure when called, which itself returns an Iterator; they can thus be used inside ClosureIterator to create new generators when needed.


Collection is a helper for making transformations to input data sets. Even though we can technically trigger side-effects in some operations through a custom Closure, it’s better to avoid this type of usage and instead use the operations for their transformative effects (use the return values).

Exception handling is one scenario where we might find ourselves wanting Collection to behave eagerly. If we want an exception to be thrown and handled in a specific function, during an operation, rather than when the collection is later iterated on, we can take advantage of the squash operation.


Working with lazy evaluation can impact how we test our code. Depending on the testing framework used, we have a few options at our disposal when it comes to comparing collections objects returned by a function.

Collection already provides two operations which can be used for comparison:

  • Equals - allows usage of the assertObjectEquals assertion in PHPUnit

  • Same - allows customizing precisely how elements are compared using a callback

Note that these operations will traverse both collections as part of the comparison. As such, any side effects triggered in our source code will be triggered during this comparison. When using equals in particular, we might find it useful to apply squash to the resulting collection object before the comparison if our test needs to assert how many times a side effect is performed.

In addition to these, in PHPUnit we can use the assertIdenticalIterable assertion to assert how our final collection object will iterate.

The last option is to transform the collection object into an array with the all operation and use any assertion that we would normally use for arrays.


Collection and the Operations are designed with usability and flexibility in mind. A few key elements that contribute to this are the usage of variadic parameters, custom callbacks, and the fact that operations can be used both as collection object methods or completely separately.

Variadic Parameters

Variadic parameters are used wherever possible in operations, allowing us to more succinctly apply multiple transformations or predicates. They will always be evaluated by the operation as a logical OR.

For example, the contains operation allows us to easily check whether one or more values are contained in the collection:



namespace App;

use loophp\collection\Collection;

include __DIR__ . '/../../../../vendor/autoload.php';

// Does it contains the letter 'd' ?
$result = Collection::fromIterable(range('a', 'c'))
    ->contains('d'); // false

// Does it contains the letter 'a' or 'z' ?
$result = Collection::fromIterable(range('a', 'c'))
    ->contains('a', 'z'); // true

// Does it contains the letter 'd' ?
$result = Collection::fromIterable(['a' => 'b', 'c' => 'd'])
    ->contains('d'); // true

If we want to instead achieve a logical AND behaviour, we can make multiple calls to the same operation. The following example using the filter operation illustrates this:



namespace App;

use loophp\collection\Collection;

include __DIR__ . '/../../../../vendor/autoload.php';

$divisibleBy2 = static fn ($value): bool => 0 === $value % 2;
$divisibleBy3 = static fn ($value): bool => 0 === $value % 3;

// Filter values divisible by 3.
$collection = Collection::fromIterable(range(1, 10))
    ->filter($divisibleBy3); // [3, 6, 9]

// Filter values divisible by 2 or 3.
$collection = Collection::fromIterable(range(1, 10))
    ->filter($divisibleBy2, $divisibleBy3); // [2, 3, 4, 6, 8, 9, 10]

// Filter values divisible by 2 and 3.
$collection = Collection::fromIterable(range(1, 10))
    ->filter($divisibleBy3); // [6]

Custom Callbacks

Many operations allow us to customize their behaviour through custom callbacks. This gives us the power to achieve what we need with the operation if the default behaviour is not the best fit for our use case.

For example, by default the same operation will compare collection elements using strict equality (===). However, when dealing with objects we might want a different behaviour:

$a = (object) ['id' => 'a'];
$a2 = (object) ['id' => 'a'];

$comparator = static fn (stdClass $left) => static fn (stdClass $right): bool => $left->id === $right->id;
    ->same(Collection::fromIterable([$a2]), $comparator); // true

Independent Operations

Operations are pure functions that can be used to transform an iterator, either directly or through the Collection object.

For example, the filter operation can be used on another iterator, independently of the Collection object. Because all operations return an iterator at the end, we can use iterator_to_array to convert this back to a normal array when needed.



namespace App;

use loophp\collection\Collection;
use loophp\collection\Operation\Filter;

include __DIR__ . '/../../../../vendor/autoload.php';

$input = [1, 2, 3, 4];
$even = static fn (int $value): bool => $value % 2 === 0;

// Standalone usage
$filtered = Filter::of()($even)($input);

print_r(iterator_to_array($filtered)); // [2, 4]

// Usage via Collection object
$filtered = Collection::fromIterable($input)->filter($even);

print_r($filtered->all()); // [2, 4]