API

Static constructors

empty

Create an empty Collection.

$collection = Collection::empty();

fromCallable

Create a collection from a callable.

$callback = static function () {
    yield 'a';
    yield 'b';
    yield 'c';
};

$collection = Collection::fromCallable($callback);

fromFile

Create a collection from a file.

Collection::fromFile('http://loripsum.net/api');

fromIterable

Create a collection from an iterable.

$collection = Collection::fromIterable(['a', 'b', 'c']);

fromResource

Create a collection from a resource.

$stream = fopen('data://text/plain,' . $string, 'rb');

$collection = Collection::fromResource($stream);

fromString

Create a collection from a string.

$data = file_get_contents('http://loripsum.net/api');

$collection = Collection::fromString($data);

range

Build a collection from a range of values.

Signature: Collection::range(int $start = 0, $end = INF, $step = 1);

$fibonacci = static function ($a = 0, $b = 1): array {
    return [$b, $a + $b];
};

$even = Collection::range(0, 20, 2); // [0, 2, 4, 6, 8, 10, 12, 14, 16, 18, 20]

Another example

$even = Collection::unfold(static function ($carry) {return $carry + 2;}, -2);
$odd = Collection::unfold(static function ($carry) {return $carry + 2;}, -1);
// Is the same as
$even = Collection::range(0, \INF, 2);
$odd = Collection::range(1, \INF, 2);

times

Create a collection by invoking a callback a given amount of times.

If no callback is provided, then it will create a simple list of incremented integers.

Signature: Collection::times($number = INF, ?callable $callback = null);

$collection = Collection::times(10);

unfold

Create a collection by yielding from a callback with a initial value.

Warning

The callback return values are reused as callback arguments at the next callback call.

Signature: Collection::unfold(callable $callback, ...$parameters);

// A list of Naturals from 1 to Infinity.
Collection::unfold(fn($n) => $n + 1, 1)
    ->normalize();
$fibonacci = static function ($a = 0, $b = 1): array {
    return [$b, $a + $b];
};

Collection::unfold($fibonacci)
    ->limit(10); // [[0, 1], [1, 1], [1, 2], [2, 3], [3, 5], [5, 8], [8, 13], [13, 21], [21, 34], [34, 55]]

Another example

$even = Collection::unfold(static function (int $carry): int {return $carry + 2;}, -2);
$odd = Collection::unfold(static function (int $carry): int {return $carry + 2;}, -1);
// Is the same as
$even = Collection::range(0, \INF, 2);
$odd = Collection::range(1, \INF, 2);

with

Warning

Will be deprecated soon. Use fromCallable, fromIterable, fromResource, fromString instead.

Create a collection with the provided data.

Signature: Collection::with($data = [], ...$parameters);

// With an iterable
$collection = Collection::with(['a', 'b']);

// With a string
$collection = Collection::with('string');

$callback = static function () {
    yield 'a';
    yield 'b';
    yield 'c';
};

// With a callback
$collection = Collection::with($callback);

// With a resource/stream
$collection = Collection::with(fopen( __DIR__ . '/vendor/autoload.php', 'r'));

Methods (operations)

Operations always returns a new collection object.

all

Convert the collection into an array.

This is a lossy operation because PHP array keys cannot be duplicated and must either be int or string.

Interface: Allable

Signature: Collection::all();

append

Add one or more items to a collection.

Warning

If appended values overwrite existing values, you might find that this operation doesn’t work correctly when the collection is converted into an array. It’s always better to never convert the collection to an array and use it in a loop. However, if for some reason, you absolutely need to convert it into an array, then use the Collection::normalize() operation.

Interface: Appendable

Signature: Collection::append(...$items);

Collection::fromIterable([1 => '1', 2 => '2', 3 => '3'])
    ->append('4'); // [1 => '1', 2 => '2', 3 => '3', 0 => '4']

Collection::fromIterable(['1', '2', '3'])
    ->append('4')
    ->append('5', '6'); // [0 => 5, 1 => 6, 2 => 3]

Collection::fromIterable(['1', '2', '3'])
    ->append('4')
    ->append('5', '6')
    ->normalize(); // ['1', '2', '3', '4', '5', '6']

apply

Execute a callback for each element of the collection without altering the collection item itself.

If the callback does not return true then it stops.

Interface: Applyable

Signature: Collection::apply(...$callbacks);

$callback = static function ($value, $key): bool
    {
        var_dump('Value is: ' . $value . ', key is: ' . $key);

        return true;
    };

$collection = Collection::fromIterable(['1', '2', '3']);

$collection
    ->apply($callback);

associate

Transform keys and values of the collection independently and combine them.

Interface: Associateable

Signature: Collection::associate(?callable $callbackForKeys = null, ?callable $callbackForValues = null);

$input = range(1, 10);

Collection::fromIterable($input)
    ->associate(
        static function ($key, $value) {
            return $key * 2;
        },
        static function ($key, $value) {
            return $value * 2;
        }
    );

// [
//   0 => 2,
//   2 => 4,
//   4 => 6,
//   6 => 8,
//   8 => 10,
//   10 => 12,
//   12 => 14,
//   14 => 16,
//   16 => 18,
//   18 => 20,
// ]

cache

Useful when using a resource as input and you need to run through the collection multiple times.

Interface: Cacheable

Signature: Collection::cache(CacheItemPoolInterface $cache = null);

$fopen = fopen(__DIR__ . '/vendor/autoload.php', 'r');

$collection = Collection::withResource($fopen)
    ->cache();

chunk

Chunk a collection of item into chunks of items of a given size.

Interface: Chunkable

Signature: Collection::chunk(int $size);

$collection = Collection::fromIterable(range(0, 10));

$collection->chunk(2);

collapse

Collapse a collection of items into a simple flat collection.

Interface: Collapseable

Signature: Collection::collapse();

$collection = Collection::fromIterable([[1,2], [3, 4]]);

$collection->collapse();

column

Return the values from a single column in the input iterables.

Interface: Columnable

Signature: Collection::column($index);

$records = [
    [
        'id' => 2135,
        'first_name' => 'John',
        'last_name' => 'Doe',
    ],
    [
        'id' => 3245,
        'first_name' => 'Sally',
        'last_name' => 'Smith',
    ],
    [
        'id' => 5342,
        'first_name' => 'Jane',
        'last_name' => 'Jones',
    ],
    [
        'id' => 5623,
        'first_name' => 'Peter',
        'last_name' => 'Doe',
    ],
];

$result = Collection::fromIterable($records)
    ->column('first_name');

combinate

Get all the combinations of a given length of a collection of items.

Interface: Combinateable

Signature: Collection::combinate(?int $length);

$collection = Collection::fromIterable(['a', 'b', 'c', 'd'])
    ->combinate(3);

combine

Combine a collection of items with some other keys.

Interface: Combineable

Signature: Collection::combine(...$keys);

$collection = Collection::fromIterable(['a', 'b', 'c', 'd'])
    ->combine('w', 'x', 'y', 'z')

compact

Remove given values from the collection, if no values are provided, it removes only the null value.

Interface: Compactable

Signature: Collection::compact(...$values);

$collection = Collection::fromIterable(['a', 1 => 'b', null, false, 0, 'c'];)
    ->compact(); // ['a', 1 => 'b', 3 => false, 4 => 0, 5 => 'c']

$collection = Collection::fromIterable(['a', 1 => 'b', null, false, 0, 'c'];)
    ->compact(null, 0); // ['a', 1 => 'b', 3 => false, 5 => 'c']

contains

Check if the collection contains one or more value.

Interface: Containsable

Signature: Collection::contains(...$value);

current

Get the value of an item in the collection given a numeric index, default index is 0.

Interface: Currentable

Signature: Collection::current(int $index = 0);

Collection::fromIterable(['a', 'b', 'c', 'd'])->current(); // Return 'a'
Collection::fromIterable(['a', 'b', 'c', 'd'])->current(0); // Return 'a'
Collection::fromIterable(['a', 'b', 'c', 'd'])->current(1); // Return 'b'
Collection::fromIterable(['a', 'b', 'c', 'd'])->current(10); // Return null

cycle

Cycle around a collection of items.

Interface: Cycleable

Signature: Collection::cycle(int $length = 0);

$collection = Collection::fromIterable(['a', 'b', 'c', 'd'])
    ->cycle(10)

diff

It compares the collection against another collection or a plain array based on its values. This method will return the values in the original collection that are not present in the given collection.

Interface: Diffable

Signature: Collection::diff(...$values);

$collection = Collection::fromIterable(['a', 'b', 'c', 'd', 'e'])
    ->diff('a', 'b', 'c', 'x'); // [3 => 'd', 4 => 'e']

diffKeys

It compares the collection against another collection or a plain object based on its keys. This method will return the key / value pairs in the original collection that are not present in the given collection.

Interface: Diffkeysable

Signature: Collection::diffKeys(...$values);

$collection = Collection::fromIterable(['a', 'b', 'c', 'd', 'e'])
    ->diffKeys(1, 2); // [0 => 'a', 3 => 'd', 4 => 'e']

distinct

Remove duplicated values from a collection.

Interface: Distinctable

Signature: Collection::distinct();

$collection = Collection::fromIterable(['a', 'b', 'c', 'd', 'a'])
    ->distinct()

drop

Drop the n first items of the collection.

Interface: Dropable

Signature: Collection::drop(int ...$counts);

Collection::fromIterable(range(10, 20))
    ->drop(2); // [12,13,14,15,16,17,18,19,20]

dropWhile

It inspects the original collection and takes from it its elements from the moment when the condition fails for the first time till the end of the list.

Interface: DropWhileable

Signature: Collection::dropWhile(callable ...$callbacks);

$isSmallerThanThree = static function (int $value): bool {
    return 3 > $value;
};

Collection::fromIterable([1,2,3,4,5,6,7,8,9,1,2,3])
    ->dropWhile($isSmallerThanThree); // [3,4,5,6,7,8,9,1,2,3]

duplicate

Find duplicated values from the collection.

Interface: Duplicateable

Signature: Collection::duplicate();

// It might returns duplicated values !
Collection::fromIterable(['a', 'b', 'c', 'a', 'c', 'a'])
        ->duplicate(); // [3 => 'a', 4 => 'c', 5 => 'a']

// Use ::distinct() and ::normalize() to get what you want.
Collection::fromIterable(['a', 'b', 'c', 'a', 'c', 'a'])
        ->duplicate()
        ->distinct()
        ->normalize() // [0 => 'a', 1 => 'c']

every

This operation tests whether all elements in the collection pass the test implemented by the provided callback.

Interface: Everyable

Signature: Collection::every(callable $callback);

$callback = static function ($value): bool {
    return $value < 20;
};

Collection::fromIterable(range(0, 10))
    ->every($callback)
    ->current(); // true

explode

Explode a collection into subsets based on a given value.

This operation use the Split operation with the flag Splitable::REMOVE and thus, values used to explode the collection are removed from the chunks.

Interface: Explodeable

Signature: Collection::explode(...$items);

$string = 'I am just a random piece of text.';

$collection = Collection::fromIterable($string)
    ->explode('o');

falsy

Check if the collection contains falsy values.

Interface: Falsyable

Signature: Collection::falsy();

filter

Filter collection items based on one or more callbacks.

Interface: Filterable

Signature: Collection::filter(callable ...$callbacks);

$callback = static function($value): bool {
    return 0 === $value % 3;
};

$collection = Collection::fromIterable(range(1, 100))
    ->filter($callback);

first

Get the first items from the collection.

Interface: Firstable

Signature: Collection::first();

$generator = static function (): Generator {
    yield 'a' => 'a';
    yield 'b' => 'b';
    yield 'c' => 'c';
    yield 'a' => 'd';
    yield 'b' => 'e';
    yield 'c' => 'f';
};

Collection::fromIterable($generator())
    ->first(); // ['a' => 'a']

flatten

Flatten a collection of items into a simple flat collection.

Interface: Flattenable

Signature: Collection::flatten(int $depth = PHP_INT_MAX);

$collection = Collection::fromIterable([0, [1, 2], [3, [4, [5, 6]]]])
    ->flatten();

flip

Flip keys and items in a collection.

Interface: Flipable

Signature: Collection::flip(int $depth = PHP_INT_MAX);

$collection = Collection::fromIterable(['a', 'b', 'c', 'a'])
    ->flip();

Tip

array_flip() and Collection::flip() can behave different, check the following examples.

When using regular arrays, array_flip() can be used to remove duplicates (dedup-licate an array).

$dedupArray = array_flip(array_flip(['a', 'b', 'c', 'd', 'a']));

This example will return ['a', 'b', 'c', 'd'].

However, when using a collection:

$dedupCollection = Collection::fromIterable(['a', 'b', 'c', 'd', 'a'])
    ->flip()
    ->flip()
    ->all();

This example will return ['a', 'b', 'c', 'd', 'a'].

foldLeft

Takes the initial value and the first item of the list and applies the function to them, then feeds the function with this result and the second argument and so on. See scanLeft for intermediate results.

Interface: FoldLeftable

Signature: Collection::foldLeft(callable $callback, $initial = null);

foldLeft1

Takes the first 2 items of the list and applies the function to them, then feeds the function with this result and the third argument and so on. See scanLeft1 for intermediate results.

Interface: FoldLeft1able

Signature: Collection::foldLeft1(callable $callback);

foldRight

Takes the initial value and the last item of the list and applies the function, then it takes the penultimate item from the end and the result, and so on. See scanRight for intermediate results.

Interface: FoldRightable

Signature: Collection::foldRight(callable $callback, $initial = null);

foldRight1

Takes the last two items of the list and applies the function, then it takes the third item from the end and the result, and so on. See scanRight1 for intermediate results.

Interface: FoldRight1able

Signature: Collection::foldRight1(callable $callback);

forget

Remove items having specific keys.

Interface: Forgetable

Signature: Collection::forget(...$keys);

$collection = Collection::fromIterable(range('a', 'z'))
    ->forget(5, 6, 10, 15);

frequency

Calculate the frequency of the values, frequencies are stored in keys.

Values can be anything (object, scalar, … ).

Interface: Frequencyable

Signature: Collection::frequency();

$collection = Collection::fromIterable(['a', 'b', 'c', 'b', 'c', 'c')
    ->frequency()
    ->all(); // [1 => 'a', 2 => 'b', 3 => 'c'];

get

Get a specific element of the collection from a key, if the key doesn’t exists, returns the default value.

Interface: Getable

Signature: Collection::get($key, $default = null);

group

Takes a list and returns a list of lists such that the concatenation of the result is equal to the argument. Moreover, each sublist in the result contains only equal elements.

Interface: Groupable

Signature: Collection::group();

Collection::fromString('Mississippi')
    ->group(); // [ [0 => 'M'], [1 => 'i'], [2 => 's', 3 => 's'], [4 => 'i'], [5 => 's', 6 => 's'], [7 => 'i'], [8 => 'p', 9 => 'p'], [10 => 'i'] ]

groupBy

Group items, the key used to group items can be customized in a callback. By default it’s the key is the item’s key.

Interface: GroupByable

Signature: Collection::groupBy(?callable $callback = null);

$callback = static function () {
        yield 1 => 'a';

        yield 1 => 'b';

        yield 1 => 'c';

        yield 2 => 'd';

        yield 2 => 'e';

        yield 3 => 'f';
};

$collection = Collection::fromIterable($callback)
    ->groupBy();

has

Check if the collection has a value. The value must be provided as a callback.

Interface: Hasable

Signature: Collection::has(callable $callback);

ifThenElse

Execute a callback when a condition is met.

Interface: IfThenElseable

Signature: Collection::ifThenElse(callable $condition, callable $then, ?callable $else = null);

$input = range(1, 5);

$condition = static function (int $value): bool {
    return 0 === $value % 2;
};

$then = static function (int $value): int {
    return $value * $value;
};

$else = static function (int $value): int {
    return $value + 2;
};

Collection::fromIterable($input)
    ->ifThenElse($condition, $then); // [1, 4, 3, 16, 5]

Collection::fromIterable($input)
    ->ifThenElse($condition, $then, $else) // [3, 4, 5, 16, 7]

implode

Convert all the elements of the collection to a single string.

The glue character can be provided, default is the empty character.

Interface: Implodeable

Signature: Collection::implode(string $glue = '');

init

Returns the collection without its last item.

Interface: Initable

Signature: Collection::init();

Collection::fromIterable(range('a', 'e'))
    ->init(); // ['a', 'b', 'c', 'd']

inits

Returns all initial segments of the collection, shortest first.

Interface: Initsable

Signature: Collection::inits();

Collection::fromIterable(range('a', 'c'))
    ->inits(); // [[], ['a'], ['a', 'b'], ['a', 'b', 'c']]

intersect

Removes any values from the original collection that are not present in the given collection.

Interface: Intersectable

Signature: Collection::intersect(...$values);

$collection = Collection::fromIterable(range('a', 'e'))
    ->intersect('a', 'b', 'c'); // ['a', 'b', 'c']

intersectKeys

Removes any keys from the original collection that are not present in the given collection.

Interface: Intersectkeysable

Signature: Collection::intersectKeys(...$values);

$collection = Collection::fromIterable(range('a', 'e'))
    ->intersectKeys(0, 2, 4); // ['a', 'c', 'e']

intersperse

Insert a given value at every n element of a collection and indices are not preserved.

Interface: Intersperseable

Signature: Collection::intersperse($element, int $every = 1, int $startAt = 0);

$collection = Collection::fromIterable(range('a', 'z'))
    ->intersperse('foo', 3);

key

Get the key of an item in the collection given a numeric index, default index is 0.

Interface: Keyable

Signature: Collection::key(int $index = 0);

Collection::fromIterable(['a', 'b', 'c', 'd'])->key(); // Return 0
Collection::fromIterable(['a', 'b', 'c', 'd'])->key(0); // Return 0
Collection::fromIterable(['a', 'b', 'c', 'd'])->key(1); // Return 1
Collection::fromIterable(['a', 'b', 'c', 'd'])->key(10); // Return null

keys

Get the keys of the items.

Interface: Keysable

Signature: Collection::keys();

$collection = Collection::fromIterable(range('a', 'z'))
    ->keys();

last

Extract the last element of a collection, which must be finite and non-empty.

Interface: Lastable

Signature: Collection::last();

$generator = static function (): Generator {
    yield 'a' => 'a';
    yield 'b' => 'b';
    yield 'c' => 'c';
    yield 'a' => 'd';
    yield 'b' => 'e';
    yield 'c' => 'f';
};

Collection::fromIterable($generator())
    ->last(); // ['c' => 'f']

limit

Limit the amount of values in the collection.

Interface: Limitable

Signature: Collection::limit(int $limit);

$fibonacci = static function ($a = 0, $b = 1): array {
    return [$b, $a + $b];
};

$collection = Collection::unfold($fibonacci)
    ->limit(10);

lines

Split a string into lines.

Interface: Linesable

Signature: Collection::lines();

$string = <<<'EOF'
The quick brow fox jumps over the lazy dog.

This is another sentence.
EOF;

Collection::fromString($string)
    ->lines();

map

Apply one or more supplied callbacks to every item of a collection and use the return value.

Warning

Keys are preserved, use the “normalize” operation if you want to re-index the keys.

Interface: Mapable

Signature: Collection::map(callable ...$callbacks);

$mapper = static function($value, $key) {
    return $value * 2;
};

$collection = Collection::fromIterable(range(1, 100))
    ->map($mapper);

merge

Merge one or more collection of items onto a collection.

Interface: Mergeable

Signature: Collection::merge(...$sources);

$collection = Collection::fromIterable(range(1, 10))
    ->merge(['a', 'b', 'c'])

normalize

Replace, reorder and use numeric keys on a collection.

Interface: Normalizeable

Signature: Collection::normalize();

$collection = Collection::fromIterable(['a' => 'a', 'b' => 'b', 'c' => 'c'])
    ->normalize();

nth

Get every n-th element of a collection.

Interface: Nthable

Signature: Collection::nth(int $step, int $offset = 0);

$collection = Collection::fromIterable(range(10, 100))
    ->nth(3);

nullsy

Check if the collection contains nullsy values.

Interface: Nullsyable

Signature: Collection::nullsy();

only

Get items having corresponding given keys.

Interface: Onlyable

Signature: Collection::only(...$keys);

$collection = Collection::fromIterable(range(10, 100))
    ->only(3, 10, 'a', 9);

pack

Wrap each items into an array containing 2 items: the key and the value.

Interface: Packable

Signature: Collection::pack();

$input = ['a' => 'b', 'c' => 'd', 'e' => 'f'];

$c = Collection::fromIterable($input)
    ->pack();

 // [
 //   ['a', 'b'],
 //   ['c', 'd'],
 //   ['e', 'f'],
 // ]

pad

Pad a collection to the given length with a given value.

Interface: Padable

Signature: Collection::pad(int $size, $value);

$collection = Collection::fromIterable(range(1, 5))
    ->pad(10, 'foo');

pair

Make an associative collection from pairs of values.

Interface: Pairable

Signature: Collection::pair();

$input = [
    [
        'key' => 'k1',
        'value' => 'v1',
    ],
    [
        'key' => 'k2',
        'value' => 'v2',
    ],
    [
        'key' => 'k3',
        'value' => 'v3',
    ],
    [
        'key' => 'k4',
        'value' => 'v4',
    ],
    [
        'key' => 'k4',
        'value' => 'v5',
    ],
];

$c = Collection::fromIterable($input)
    ->unwrap()
    ->pair()
    ->group()
    ->all();

// [
//    [k1] => v1
//    [k2] => v2
//    [k3] => v3
//    [k4] => [
//        [0] => v4
//        [1] => v5
//    ]
// ]

permutate

Find all the permutations of a collection.

Interface: Permutateable

Signature: Collection::permutate(int $size, $value);

$collection = Collection::fromIterable(['hello', 'how', 'are', 'you'])
    ->permutate();

pluck

Retrieves all of the values of a collection for a given key.

Interface: Pluckable

Signature: Collection::pluck($pluck, $default = null);

$fibonacci = static function ($a = 0, $b = 1): array {
    return [$b, $a + $b];
};

$collection = Collection::unfold($fibonacci)
    ->limit(10)
    ->pluck(0);

prepend

Push an item onto the beginning of the collection.

Warning

If prepended values overwrite existing values, you might find that this operation doesn’t work correctly when the collection is converted into an array. It’s always better to never convert the collection to an array and use it in a loop. However, if for some reason, you absolutely need to convert it into an array, then use the Collection::normalize() operation.

Interface: Prependable

Signature: Collection::prepend(...$items);

Collection::fromIterable([1 => '1', 2 => '2', 3 => '3'])
    ->prepend('4'); // [0 => 4, 1 => '1', 2 => '2', 3 => '3']

Collection::fromIterable(['1', '2', '3'])
    ->prepend('4')
    ->prepend('5', '6'); // [0 => 1, 1 => 2, 2 => 3]

Collection::fromIterable(['1', '2', '3'])
    ->prepend('4')
    ->prepend('5', '6')
    ->normalize(); // ['5', '6', '4', '1', '2', '3']

product

Get the the cartesian product of items of a collection.

Interface: Productable

Signature: Collection::product(iterable ...$iterables);

$collection = Collection::fromIterable(['4', '5', '6'])
    ->product(['1', '2', '3'], ['a', 'b'], ['foo', 'bar']);

random

It returns a random item from the collection. An optional integer can be passed to random to specify how many items you would like to randomly retrieve.

Interface: Randomable

Signature: Collection::random(int $size = 1);

$collection = Collection::fromIterable(['4', '5', '6'])
    ->random(); // ['6']

reduction

Reduce a collection of items through a given callback.

Interface: Reductionable

Signature: Collection::reduction(callable $callback, $initial = null);

$multiplication = static function ($value1, $value2) {
    return $value1 * $value2;
};

$addition = static function ($value1, $value2) {
    return $value1 + $value2;
};

$fact = static function (int $number) use ($multiplication) {
    return Collection::range(1, $number + 1)
        ->reduce(
            $multiplication,
            1
        );
};

$e = static function (int $value) use ($fact): float {
    return $value / $fact($value);
};

$number_e_approximation = Collection::times()
    ->map($e)
    ->limit(10)
    ->reduction($addition);

reverse

Reverse order items of a collection.

Interface: Reverseable

Signature: Collection::reverse();

$collection = Collection::fromIterable(['a', 'b', 'c'])
    ->reverse();

rsample

Work in progress… sorry.

scale

Scale/normalize values.

Interface: Scaleable

Signature: Collection::scale(float $lowerBound, float $upperBound, ?float $wantedLowerBound = null, ?float $wantedUpperBound = null, ?float $base = null);

$collection = Collection::range(0, 10, 2)
    ->scale(0, 10);

$collection = Collection::range(0, 10, 2)
    ->scale(0, 10, 5, 15, 3);

scanLeft

Takes the initial value and the first item of the list and applies the function to them, then feeds the function with this result and the second argument and so on. It returns the list of intermediate and final results.

Interface: ScanLeftable

Signature: Collection::scanLeft(callable $callback, $initial = null);

$callback = static function ($carry, $value) {
    return $carry / $value;
};

Collection::fromIterable([4, 2, 4])
    ->scanLeft($callback, 64)
    ->normalize(); // [64 ,16 ,8 ,2]

Collection::empty()
    ->scanLeft($callback, 3)
    ->normalize(); // [3]

scanLeft1

Takes the first 2 items of the list and applies the function to them, then feeds the function with this result and the third argument and so on. It returns the list of intermediate and final results.

Warning

You might need to use the normalize operation after this.

Interface: ScanLeft1able

Signature: Collection::scanLeft1(callable $callback);

$callback = static function ($carry, $value) {
    return $carry / $value;
};

Collection::fromIterable([64, 4, 2, 8])
    ->scanLeft1($callback); // [64 ,16 ,8 ,1]

Collection::fromIterable([12])
    ->scanLeft1($callback); // [12]

scanRight

Takes the initial value and the last item of the list and applies the function, then it takes the penultimate item from the end and the result, and so on. It returns the list of intermediate and final results.

Interface: ScanRightable

Signature: Collection::scanRight(callable $callback, $initial = null);

$callback = static function ($carry, $value) {
    return $value / $carry;
};

Collection::fromIterable([8, 12, 24, 4])
    ->scanRight($callback, 2); // [8, 1, 12, 2, 2]

Collection::empty()
    ->scanRight($callback, 3); // [3]

scanRight1

Takes the last two items of the list and applies the function, then it takes the third item from the end and the result, and so on. It returns the list of intermediate and final results.

Warning

You might need to use the normalize operation after this.

Interface: ScanRight1able

Signature: Collection::scanRight1(callable $callback);

$callback = static function ($carry, $value) {
    return $value / $carry;
};

Collection::fromIterable([8, 12, 24, 2])
    ->scanRight1($callback); // [8, 1, 12, 2]

Collection::fromIterable([12])
    ->scanRight1($callback); // [12]

since

Skip items until callback is met.

Interface: Sinceable

Signature: Collection::since(callable ...$callbacks);

// Parse the composer.json of a package and get the require-dev dependencies.
$collection = Collection::withResource(fopen(__DIR__ . '/composer.json', 'rb'))
    // Group items when EOL character is found.
    ->split(
        static function (string $character): bool {
            return "\n" === $character;
        }
    )
    // Implode characters to create a line string
    ->map(
        static function (array $characters): string {
            return implode('', $characters);
        }
    )
    // Skip items until the string "require-dev" is found.
    ->since(
        static function ($line) {
            return false !== strpos($line, 'require-dev');
        }
    )
    // Skip items after the string "}" is found.
    ->until(
        static function ($line) {
            return false !== strpos($line, '}');
        }
    )
    // Re-index the keys
    ->normalize()
    // Filter out the first line and the last line.
    ->filter(
        static function ($line, $index) {
            return 0 !== $index;
        },
        static function ($line) {
            return false === strpos($line, '}');
        }
    )
    // Trim remaining results and explode the string on ':'.
    ->map(
        static function ($line) {
            return trim($line);
        },
        static function ($line) {
            return explode(':', $line);
        }
    )
    // Take the first item.
    ->pluck(0)
    // Convert to array.
    ->all();

    print_r($collection);

slice

Get a slice of a collection.

Interface: Sliceable

Signature: Collection::slice(int $offset, ?int $length = null);

$collection = Collection::fromIterable(range('a', 'z'))
    ->slice(5, 5);

sort

Sort a collection using a callback. If no callback is provided, it will sort using natural order.

By default, it will sort by values and using a callback. If you want to sort by keys, you can pass a parameter to change the behavior or use twice the flip operation. See the example below.

Interface: Sortable

Signature: Collection::sort(?callable $callback = null);

// Regular values sorting
$collection = Collection::fromIterable(['z', 'y', 'x'])
    ->sort();

// Regular values sorting
$collection = Collection::fromIterable(['z', 'y', 'x'])
    ->sort(Operation\Sortable::BY_VALUES);

// Regular values sorting with a custom callback
$collection = Collection::fromIterable(['z', 'y', 'x'])
    ->sort(
            Operation\Sortable::BY_VALUES,
            static function ($left, $right): int {
                // Do the comparison here.
                return $left <=> $right;
            }
    );

// Regular keys sorting (no callback is needed here)
$collection = Collection::fromIterable(['z', 'y', 'x'])
    ->sort(
            Operation\Sortable::BY_KEYS
    );

// Regular keys sorting using flip() operations.
$collection = Collection::fromIterable(['z', 'y', 'x'])
    ->flip() // Exchange values and keys
    ->sort() // Sort the values (which are now the keys)
    ->flip(); // Flip again to put back the keys and values, sorted by keys.

span

Returns a tuple where first element is longest prefix (possibly empty) of elements that satisfy the callback and second element is the remainder.

Interface: Spanable

Signature: Collection::span(callable $callback);

$input = range(1, 10);

Collection::fromIterable($input)
    ->span(fn ($x) => $x < 4); // [ [1, 2, 3], [4, 5, 6, 7, 8, 9, 10] ]

split

Split a collection using one or more callbacks.

A flag must be provided in order to specify whether the value used to split the collection should be added at the end of a chunk, at the beginning of a chunk, or completely removed.

Interface: Splitable

Signature: Collection::split(int $type = Splitable::BEFORE, callable ...$callbacks);

$splitter = static function ($value): bool {
    return 0 === $value % 3;
};

$collection = Collection::fromIterable(range(0, 10))
    ->split(Splitable::BEFORE, $splitter); [[0, 1, 2], [3, 4, 5], [6, 7, 8], [9, 10]]

$collection = Collection::fromIterable(range(0, 10))
    ->split(Splitable::AFTER, $splitter); [[0], [1, 2, 3], [4, 5, 6], [7, 8, 9], [10]]

$collection = Collection::fromIterable(range(0, 10))
    ->split(Splitable::REMOVE, $splitter); [[1, 2], [4, 5], [7, 8], [10]]

tail

Get the collection items except the first.

Interface: Tailable

Signature: Collection::tail();

Collection::fromIterable(['a', 'b', 'c'])
    ->tail(); // [1 => 'b', 2 => 'c']

tails

Returns the list of initial segments of its argument list, shortest last.

Interface: Tailsable

Signature: Collection::tails();

Collection::fromIterable(['a', 'b', 'c'])
    ->tails(); // [['a', 'b', 'c'], ['b', 'c'], ['c'], []]

takeWhile

It inspects the original collection and takes from it its elements to the moment when the condition fails, then it stops processing.

Interface: TakeWhileable

Signature: Collection::takeWhile(callable $callback);

$isSmallerThanThree = static function (int $value): bool {
    return 3 > $value;
};

Collection::fromIterable([1,2,3,4,5,6,7,8,9,1,2,3])
    ->takeWhile($isSmallerThanThree); // [1,2]

transpose

Matrix transposition.

Interface: Transposeable

Signature: Collection::transpose();

$records = [
    [
        'id' => 2135,
        'first_name' => 'John',
        'last_name' => 'Doe',
    ],
    [
        'id' => 3245,
        'first_name' => 'Sally',
        'last_name' => 'Smith',
    ],
    [
        'id' => 5342,
        'first_name' => 'Jane',
        'last_name' => 'Jones',
    ],
    [
        'id' => 5623,
        'first_name' => 'Peter',
        'last_name' => 'Doe',
    ],
];

$result = Collection::fromIterable($records)
    ->transpose();

truthy

Check if the collection contains truthy values.

Interface: Truthyable

Signature: Collection::truthy();

unlines

Create a string from lines.

Interface: Unlinesable

Signature: Collection::unlines();

$lines = [
    'The quick brow fox jumps over the lazy dog.',
    '',
    'This is another sentence.',
];

Collection::fromIterable($lines)
    ->unlines()
    ->current();

unpack

Unpack items.

Interface: Unpackable

Signature: Collection::unpack();

$input = [['a', 'b'], ['c', 'd'], ['e', 'f']];

$c = Collection::fromIterable($input)
    ->unpack();

// [
//     ['a' => 'b'],
//     ['c' => 'd'],
//     ['e' => 'f'],
// ];

unpair

Unpair a collection of pairs.

Interface: Unpairable

Signature: Collection::unpair();

$input = [
    'k1' => 'v1',
    'k2' => 'v2',
    'k3' => 'v3',
    'k4' => 'v4',
];

$c = Collection::fromIterable($input)
    ->unpair();

// [
//     ['k1', 'v1'],
//     ['k2', 'v2'],
//     ['k3', 'v3'],
//     ['k4', 'v4'],
// ];

until

Limit a collection using a callback.

Interface: Untilable

Signature: Collection::until(callable ...$callbacks);

// The Collatz conjecture (https://en.wikipedia.org/wiki/Collatz_conjecture)
$collatz = static function (int $value): int
{
    return 0 === $value % 2 ?
        $value / 2:
        $value * 3 + 1;
};

$collection = Collection::unfold($collatz, 10)
    ->until(static function ($number): bool {
        return 1 === $number;
    });

unwindow

Contrary of Collection::window(), usually needed after a call to that operation.

Interface: Unwindowable

Signature: Collection::unwindow();

// Drop all the items before finding five 9 in a row.
$input = [1, 2, 3, 4, 5, 6, 7, 8, 9, 9, 9, 9, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18];

Collection::fromIterable($input)
    ->window(4)
    ->dropWhile(
        static function (array $value): bool {
            return $value !== [9, 9, 9, 9, 9];
        }
    )
    ->unwindow()
    ->drop(1)
    ->normalize(); // [10, 11, 12, 13, 14, 15, 16, 17, 18]

unwords

Create a string from words.

Interface: Unwordsable

Signature: Collection::unwords();

$words = [
    'The',
    'quick',
    'brow',
    'fox',
    'jumps',
    'over',
    'the',
    'lazy',
    "dog.\n\nThis",
    'is',
    'another',
    'sentence.',
];

Collection::fromIterable($words)
    ->unwords();

unwrap

Unwrap every collection element.

Interface: Unwrapable

Signature: Collection::unwrap();

$data = [['a' => 'A'], ['b' => 'B'], ['c' => 'C']];

$collection = Collection::fromIterable($data)
   ->unwrap();

unzip

Unzip a collection.

Interface: Unzipable

Signature: Collection::unzip();

$a = Collection::fromIterable(['a' => 'a', 'b' => 'b', 'c' => 'c'])
    ->zip(['d', 'e', 'f', 'g'], [1, 2, 3, 4, 5]);

$b = Collection::fromIterable($a)
    ->unzip(); // [ ['a','b','c',null,null], ['d','e','f','g',null], [1,2,3,4,5] ]

window

Loop the collection by yielding a specific window of data of a given length.

Interface: Windowable

Signature: Collection::window(int $size);

$data = range('a', 'z');

Collection::fromIterable($data)
   ->window(2)
   ->all(); // [ ['a'], ['a', 'b'], ['b', 'c'], ['c', 'd'], ... ]

words

Get words from a string.

Interface: Wordsable

Signature: Collection::words();

$string = <<<'EOF'
The quick brow fox jumps over the lazy dog.

This is another sentence.
EOF;

Collection::fromString($string)
    ->words()

wrap

Wrap every element into an array.

Interface: Wrapable

Signature: Collection::wrap();

$data = ['a' => 'A', 'b' => 'B', 'c' => 'C'];

$collection = Collection::fromIterable($data)
   ->wrap();

zip

Zip a collection together with one or more iterables.

Interface: Zipable

Signature: Collection::zip(iterable ...$iterables);

$even = Collection::range(0, INF, 2);
$odd = Collection::range(1, INF, 2);

$positiveIntegers = Collection::fromIterable($even)
    ->zip($odd)
    ->limit(100)
    ->flatten();