innmind/immutable

Immutable PHP primitive wrappers

Maintainers

👁 Baptouuuu

Package info

github.com/Innmind/Immutable

Homepage

Issues

pkg:composer/innmind/immutable

Statistics

Installs: 228 399

Dependents: 66

Suggesters: 0

Stars: 74

6.2.0 2026-05-14 13:47 UTC

Requires

  • php: ~8.4

Suggests

Provides

Conflicts

Replaces

None

MIT 36265de347c72ffe0915b3b1933fa36b8c95f70e

  • Baptiste Langlade <baptiste.langlade.woop@hey.com>

wrapperimmutable

This package is auto-updated.

Last update: 2026-06-14 14:00:33 UTC

README

👁 Build Status
👁 codecov
👁 Type Coverage

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
 });
 }
}