PHP Collection

Description

Collection is a functional utility library for PHP greater than 7.4, including
PHP 8.0.

It's similar to other 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 file. Instead of
reading and storing 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:

is immutable,
is extendable,
extensively uses S.O.L.I.D. principles,
leverages the power of PHP generators and iterators,
extensively tested,
uses strict types,
framework agnostic.

Except for 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 lets you use any kind of type for keys:
integer, string, object, array, ... 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; while it might lead to some confusion at first, please carefully
read this example for the full explanation and benefits.

This library has been inspired by:

Features

Decoupled: Each Collection method 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 100
operations are available in this library. This library is an example of
what you can do with all those small bricks, but nothing prevents users from
using 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
<?php

$input = ['foo', 'bar', 'baz'];

// Using the Collection library
$collection = Collection::fromIterable($input)
    ->filter(static fn(string $userId): bool => 'foo' !== $userId)
    ->reverse();

foreach ($collection as $item); // ['baz','bar']

// Using single operations.
$pipe = Pipe::of()(
  Reverse::of(),
  Filter::of()($filterCallback)
);

foreach ($pipe($input) as $item); // ['baz','bar']
```
More information about this in the Brian Lonsdorf's conference, even if
this is for JavaScript, those concepts are common in 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
<?php

$input = ['foo,bar', 'baz,john'];

$flatMap = static fn (callable $callback) =>
  Pipe::of()(
      Map::of()(static fn(string $name): array => explode(',', $name)),
      Flatten::of()(1)
  );

foreach ($flatMap($input) as $item); // ['foo', 'bar', 'baz', 'john']
```

Installation

composer require loophp/collection

Usage

Check out the usage page for both trivial and more advanced use cases.

Dependencies

loophp/iterators: A package providing PHP Iterators.

Documentation

On top of well-documented code, the package includes a complete documentation
that gets automatically compiled and published upon each commit at
https://loophp-collection.rtfd.io.

The Collection Principles will get you started with understanding the
elements that are at the core of this package, so you can get the most out of
its usage.

The API will give you a pretty good idea of the existing methods and what
you can do with them.

We are doing our best to keep the documentation up to date; if you found
something odd, please let us know in the issue queue.

Code quality, tests, benchmarks

Every time changes are introduced into the library,
Github runs the tests.

The library has tests written with PHPUnit. Feel free to check them out in
the tests/unit/ directory. Run composer phpunit to trigger the tests.

Before each commit, some inspections are executed with GrumPHP; run
composer grumphp to check manually.

The quality of the tests is tested with Infection a PHP Mutation testing
framework - run composer infection to try it.

Static analyzers are also controlling the code. PHPStan and PSalm
are enabled to their maximum level.

Contributing

Feel free to contribute by sending pull requests. We are a usually very
responsive team and we will help you going through your pull request from the
beginning to the end, read more about it in the
documentation.

For some reasons, if you can't contribute to the code and willing to help,
sponsoring is a good, sound and safe way to show us some gratitude for the hours
we invested in this package.

Sponsor me on Github and/or any of the
contributors.