Download the PHP package bonami/collections without Composer

Collections for PHP with focus on Immutability and Functional Programming

Table of contents

• Motivation
• Show me the code!
• Features
  • Structures
  • Type safety
• Advanced topics:
  • Type classes
  • Lift operator
  • Currying
  • Traverse
• License
• Contributing

Motivation

Why yet another collections library for PHP? Native PHP arrays or SPL structures like SplFixedArray or SplObjectStorage(and other) are mutable and has very strange interfaces and behaviors. They often represent more data structures at once (eg. SplObjectStorage represents both Set and Map) and theirs interfaces are designed for classic imperative approach.

We tried to design interfaces of our structures to be focused on declarative approach leveraging functional programing. For more safety, we designed structures to be immutable (we have some mutables as well, because sometime it is necessary for performance reasons)

All the code is designed to be type safe with phpstan generics.

Show me the code!

A code example is worth a thousand words, so here are some simple examples:

Filtering Person DTOs and extracting some information

Generating combinations

Generating combinations with lift

Character frequency analysis

Features

Structures

• \Bonami\Collection\ArrayList - An immutable (non associative) array wrapper, meant for sequential processing.
• \Bonami\Collection\Map - An immutable key-value structure. It can contain any kind of object as keys (with some limitation, see further info in docs).
• \Bonami\Collection\Mutable\Map - Mutable variant of Map.
• \Bonami\Collection\LazyList - Wrapper on any iterable structure. It leverages yield internally making it lazy. It can save memory significantly.
• \Bonami\Collection\Enum - Not a collection, but has great synergy with rest of the library. Meant for defining closed enumerations. Provides interesting methods like getting complements list of values for given enum.
• \Bonami\Collection\EnumList - List of Enums, extending ArrayList
• \Bonami\Collection\Option - Immutable structure for representing, that you maybe have value and maybe not. It provides safe (functional) approach to handle null pointer errors.
• \Bonami\Collection\TrySafe - Immutable structure for representing, that you have value or error generated upon the way. It provides safe (functional) approach to handle errors without side effects.
• \Bonami\Collection\CurriedFunction - Represents single argument function. It can create curried version of multi argument function, which is better for some function programming composition patterns.

Type safety

We are using phpstan annotations for better type safety, utilizing generics. For even better type resolving, we created optional dependency phpstan-collections, which we strongly suggest installing if you use phpstan. It fixes some type resolving, especially for late static binding.

Traverse

You may find yourself in situation, where you map list using mapper function which returns values wrapped in Option but you'd rather have values unwrapped. And that is when traverse method comes handy:

Compare the result with usage of our old buddy ArrayList::map:

Did you spot the difference? We have list of options with strings inside here whereas we have option of list with strings inside in the first code example.

So traverse allows us to convert list of Options to Option of list with unwrapped values. And guess what - as usual, None will ruin everything:

Usage of traverse method is not limited to Option class. It will work with any applicative, so it is available for TrySafe, ArrayList & LazyList (Failure & empty list instances behave the same way as None).

License

This package is released under the MIT license.

Contributing

If you wish to contribute to the project, please read the CONTRIBUTING notes.