• Stars
    star
    721
  • Rank 62,797 (Top 2 %)
  • Language
    PHP
  • License
    MIT License
  • Created about 5 years ago
  • Updated 21 days ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A (memory) friendly, easy, lazy and modular collection class.

Try! Latest Stable Version GitHub stars Total Downloads GitHub Workflow Status Scrutinizer code quality Type Coverage Code Coverage Mutation testing badge License Donate!

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:

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
    
    $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
    
    $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

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.

On the internet

Changelog

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

For more detailed changelogs, please check the release changelogs.

More Repositories

1

nix-shell

Nix shells for PHP development
Nix
154
star
2

combinator

A curated list of combinators
PHP
107
star
3

phptree

An implementation of tree data structure
PHP
93
star
4

iterators

The missing PHP iterators.
PHP
35
star
5

rust-shell

Nix shells for Rust development
Nix
27
star
6

fpt

Functional programming toolbox for PHP.
PHP
27
star
7

dynamicobjects

Create PHP objects having dynamic classes and/or properties.
PHP
15
star
8

nix-php-composer-builder

A PHP builder for Composer based projects
Nix
13
star
9

memoize

Memoize a closure.
PHP
13
star
10

mock-soapclient

A fake and predictable SOAP client, useful for your unit tests.
PHP
13
star
11

repository-monadic-helper

Monadic Doctrine repositories helper classes and services.
PHP
12
star
12

launcher

Open a file or a resource with the default OS application.
PHP
11
star
13

tin

Taxpayer Identification Number (TIN) Validator
PHP
9
star
14

phptree-ast-generator

Generates Abstrax Syntax Tree (AST) of a PHP script in DOT (Graphviz) or Image (PNG, JPG, SVG) formats.
PHP
9
star
15

unaltered-psr-http-message-bridge-bundle

Provide a PSR HTTP message bridge without altering query parameters.
PHP
5
star
16

nanobench

A simple and lightweight benchmarking tool for PHP.
PHP
5
star
17

church-encoding

Church encoding in PHP
PHP
4
star
18

php-src-nix

PHP builds for Nix, with Nix.
Nix
4
star
19

phposinfo

Try to guess the host operating system.
PHP
4
star
20

typed-generators

Generate random typed values and in any shape.
PHP
3
star
21

psr-http-message-bridge-bundle

Register symfony/psr-http-message-bridge classes in your Symfony application.
PHP
3
star
22

ci-detector

To detect whether we are in a CI or not
Nix
3
star
23

go-unfloc-yourself-bundle

Adds a specific header to every response to disable Google's usage of your site in it's FLoC tracking method.
PHP
3
star
24

flake-lock-update-workflow

Provide a 'ready-to-use' Github workflow to update 'flake.lock' file automatically.
Nix
2
star
25

grumphp-license-task

Provide the license task for GrumPHP.
PHP
2
star
26

nix-auto-changelog

A Nix flake to generating changelog files based on your git tags and commit history.
Nix
2
star
27

phpunit-iterable-assertions

Iterable assertions for PHPUnit
PHP
2
star
28

psr17

Provides a PSR17 synthetic implementation.
PHP
1
star
29

DockLatex

A multi-platform Docker-based LaTeX workspace for a quickstart and easy hands on.
TeX
1
star
30

nix-phpstan

A Nix flake for PHPStan
Nix
1
star
31

php-semver-bin

PHP
1
star
32

phpspec-time

A PHPSpec extension providing matchers for measuring time in tests.
PHP
1
star
33

nix-prettier

A Nix flake to run Prettier in a project without worries.
Nix
1
star
34

service-alias-autoregister-bundle

Auto register services aliases in the Symfony container.
PHP
1
star