README

A set of classes to wrap PHP primitives to build immutable data.

Documentation

Installation

composer require innmind/immutable

Usage

Here are some examples of what you can do:

Sequence

To be used to wrap an ordered list of elements (elements can be of mixed types).

use Innmind\Immutable\Sequence;

$seq = Sequence::of(24, 42, 'Hitchhiker', 'Magrathea');
$seq->get(2); // Maybe::just(Hitchhiker)
$another = $seq->drop(2);
$another->toList(); // [Hitchhiker, Magrathea]
$seq->toList(); // [24, 42, Hitchhiker, Magrathea]

//----
// this example demonstrates the lazyness capability of the sequence
// precisely here it's able to read a file line by line and echo the lines
// that are less than 42 characters long (without requiring to load the whole
// file in memory)
$someFile = fopen('some/file.txt', 'r');
$lines = Sequence::lazy(fn() => yield fgets($someFile))
    ->filter(fn($line) => strlen($line) < 42);
// at this point no reading to the file has been done because all methods
// returning a new instance of a sequence will pipeline the operations to do,
// allowing to chain complex logic while accessing the original data once and
// without the need to keep the discarded data along the pipeline in memory
$lines->foreach(fn($line) => echo($line));

For a complete list of methods check Sequence.

Set

To be used as a collection of unordered elements (elements must be of the same type).

use Innmind\Immutable\Set;

$set = Set::of(24, 42);
$set->equals(Set::of(24, 42)); // true
$set->add(42.0); // psalm will raise an error

For a complete list of methods check Set.

Map

To be used as a collection of key/value pairs (both keys and values must be of the same type).

use Innmind\Immutable\Map;

$map = Map::of(
    [new \stdClass, 42]
    [$key = new \stdClass, 24]
);
$map->size(); // 2, because it's 2 different instances
$map->values()->toList(); // [42, 24]
$map = $map->put($key, 66);
$map->size(); // 2
$map->values()->toList(); // [42, 66]

For a complete list of methods check Map.

Strings

use Innmind\Immutable\Str;

$var = Str::of('the hitchhiker\'s guide to the galaxy');
echo $var
    ->replace('galaxy', '42') // the hitchhiker's guide to the 42
    ->drop(18) // guide to the 42
    ->toUpper()
    ->toString(); // outputs: GUIDE TO THE 42
echo $var->toString(); // outputs: the hitchhiker\'s guide to the galaxy

Regular expressions

use Innmind\Immutable\{
    RegExp,
    Str,
};

$regexp = RegExp::of('/(?<i>\d+)/');
$regexp->matches(Str::of('foo123bar')); // true
$regexp->matches(Str::of('foobar')); // false
$regexp->capture(Str::of('foo123bar')); // Map<int|string, Str> with index `i` set to Str::of('123')

BlackBox

This library provides 2 Sets that can be used with innmind/black-box.

You can use them as follow:

use Innmind\BlackBox\{
    PHPUnit\BlackBox,
    Set,
};
use Fixtures\Innmind\Immutable;

class SomeTest extends \PHPUnit\Framework\TestCase
{
    use BlackBox;

    public function testSomeProperty()
    {
        $this
            ->forAll(
                Immutable\Set::of(
                    Set\RealNumbers::any(),
                ),
                Immutable\Sequence::of(
                    Set\Uuid::any(),
                ),
            )
            ->then(function($set, $sequence) {
                // $set is an instance of \Innmind\Immutable\Set<float>
                // $sequence is an instance of \Innmind\Immutable\Sequence<string>

                // write your test here
            });
    }
}