PHP Collection

Collection is a functional utility library for PHP greater than 7.1.3.

It’s similar to other available collection libraries based on regular PHP arrays, but with a lazy mechanism under the hood that strives to do as little work as possible while being as flexible as possible.

Functions like array_map(), array_filter() and array_reduce() are great, but they create new arrays and everything is eagerly done before going to the next step. Lazy collection leverages PHP’s generators, iterators and yield statements to allow you to work with very large data sets while keeping memory usage as low as possible.

For example, imagine your application needs to process a multi-gigabyte log file while taking advantage of this library’s methods to parse the logs. Instead of reading the entire file into memory at once, this library may be used to keep only a small part of the file in memory at a given time.

On top of this, this library:

Except a few methods, most methods are pure and return a new Collection object.

Also, unlike regular PHP arrays where keys must be either of type int or string, this collection library let you use any kind of type for keys: integer, string, objects, arrays, … anything! This library could be a valid replacement for SplObjectStorage but with much more features. This way of working opens up new perspectives and another way of handling data, in a more functional way.

And last but not least, collection keys are preserved throughout most operations, and it might be leading to some confusions, carefully read this example for the full explanation.

This library has been inspired by:

Features

  • Decoupled: Each Collection methods is a shortcut to one isolated standard class, each operation has its own responsibility. Usually the arguments needed are standard PHP variables like int, string, callable or iterator. It allows users to use those operations individually, at their own will to build up something custom. Currently, more than 80 operations are available in this library. This library is basically an example of what you can do with all those small bricks, but nothing prevent users to use an operation on its own as well.

  • It takes function first, data-last: In the following example, multiple operations are created. The data to be operated on is generally supplied at last.

    <?php
    
    $data = ['foo', 'bar', 'baz'];
    $filterCallback = static fn(string $userId): bool => 'foo' !== $userId;
    
    // Using the Collection library
    $collection = Collection::fromIterable($data)
        ->filter($filterCallback)
        ->reverse();
    print_r($collection->all()); // ['baz', 'bar']
    
    // Using single operations.
    $filter = Filter::of()($filterCallback);
    $reverse = Reverse::of();
    $pipe = Pipe::of()($reverse, $filter);
    
    print_r(iterator_to_array($pipe(new ArrayIterator($data))));  // ['baz', 'bar']
    

    More information about this in the Brian Lonsdorf’s conference, even if this is for Javascript, those concepts are common to other programming languages.

    In a nutshell, the combination of currying and function-first enables the developer to compose functions with very little code (often in a “point-free” fashion), before finally passing in the relevant user data.

  • Operations are stateless and curried by default: This currying makes it easy to compose functions to create new functions. Because the API is function-first, data-last, you can continue composing and composing until you build up the function you need before dropping in the data. See this Hugh Jackson article describing the advantages of this style.

    In the following example, the well-known flatMap could be composed of other operations as such:

    <?php
    
    $input = ['foo,bar', 'baz,john'];
    $userData = new ArrayIterator($input);
    
    $flatMap = static fn (callable $callable) =>
                   Pipe::of()(
                      Map::of()($callable),
                      Flatten::of()(1),
                      Normalize::of()
                   );
    
    $callback = fn(string $name): array => explode(',', $name);
    
    print_r(iterator_to_array($flatMap($callback)($userData))); // ['foo', 'bar', 'baz', 'john']
    

Changelog

See CHANGELOG.md for a changelog based on git commits.

For more detailed changelogs, please check the release changelogs.