README

A library that provides a set of minimalist, typed and piped Immutable Collections for PHP.

Requirements

PHP > 7.2

Installation

composer require dcsg/php-immutable-collections

What Problems does this solve?

The lack of Generics in PHP does not allow to have typed collections in PHP.

This Library provides two abstract Immutable Collections:

Immutable List Collection - ImmutableCollection
Immutable Set Collection - SetImmutableCollection

Why Typed Immutable Collections

Typed Collections

Since PHP does not have Generics like Java has, it's not possible to have native typed collections. The Collections available in this Library are the foundation for you to create your own Typed Collections, you just need to extend them.

Typed Immutable Collections for DDD (Domain Driven Design)

DDD is all about having your code speaking the business language, the called Ubiquitous Language. Without Collections in PHP this is very hard to achieve using Arrays because you cannot add behavior to them. So what usually happens you add that behavior to your entity but it shouldn't be there. Another problem is the mutability of Arrays, VOs (Value Objects) MUST be always immutable and that's impossible with Arrays and you should always guarantee that the elements of that Array are all of the same type.

Collections vs Arrays

Collections and Arrays both represent a Group of Elements.
Collections are not natively supported by PHP while Arrays are.
Arrays is THE data structure of PHP and is used for almost everything.
Arrays don't allow you to add new behavior while Collections allow it.
Arrays don't allow you to define a type for its elements while Collections allow it.

Other PHP Collections

There are other Collections for PHP out there, naming a few we have Doctrine Collections and Illuminate Collections. Those collections they solve different problems, are tailored to their specific use case, and their APIs are extensive and more important those Collections are Mutable. These combinations make it difficult to use those Collections for more simple use cases. That's why the Collections we provide here, have a very small API and don't even expose the Iterator API. This way you have the possibility to use them and extend it's behavior tailored for your needs.

Features

Static construction for pipe usage.
Util methods like isEmpty, count, toArray, contains, get ,map, filter, slice, merge, reverse, reduce, first, last, head, tail.

Basic usage

Creating a Typed List Collection

<?php declare(strict_types=1);

use DCSG\ImmutableCollections\ImmutableCollection;

final class MyStringCollection extends ImmutableCollection {
    protected function validateItems(array $elements): void
    {
        foreach ($elements as $element) {
            if (!\is_string($element)) {
                throw new InvalidArgumentException('Element is not a String.');
            }
        }
    }
}

$collection = MyStringCollection::create(['foo', 'bar']);
echo $collection->count(); // 2
$slicedCollection = $collection->slice(0, 1); // MyStringCollection { $elements=['foo']}

Creating a Typed Set Collection

<?php declare(strict_types=1);

use DCSG\ImmutableCollections\SetImmutableCollection;

final class MyStringSetCollection extends SetImmutableCollection {
    protected function validateItems(array $elements): void
    {
        foreach ($elements as $element) {
            if (!\is_string($element)) {
                throw new InvalidArgumentException('Element is not a String.');
            }
        }
    }
}

$collection = MyStringSetCollection::create(['foo', 'bar']);
echo $collection->count(); // 2
$slicedCollection = $collection->tail(); // MyStringSetCollection { $elements=['bar']}

$collection = MyStringSetCollection::create(['foo', 'bar', 'foo']); // Throws InvalidArgumentException

Examples

We provide two simple examples for better understanding. One related to invoices and another one regarding Legs of a Cargo Ship.

Change log

Please see CHANGELOG for more information on what has changed recently.

Testing

$ composer test

Contributing

Please see CONTRIBUTING and CODE OF CONDUCT for details.

Security

If you discover any security related issues, please email hi@dcsg.me instead of using the issue tracker.

Credits

License

The MIT License (MIT). Please see License File for more information.

dcsg / php-immutable-collections

Maintainers

Details