mf/collections-php

Collections for PHP - It's basically a syntax sugar over classic array structure, which allows you to use it as classic array, but adds some cool features.

8.3.0 2023-12-13 08:13 UTC

Requires

• php: ^8.2
• ext-mbstring: *
• beberlei/assert: ^3.0

Requires (Dev)

• ergebnis/composer-normalize: ^2.40
• lmc/coding-standard: ^3.3
• mockery/mockery: ^1.6.7
• php-parallel-lint/php-parallel-lint: ^1.3.2
• phpstan/extension-installer: ^1.3.1
• phpstan/phpstan: ^1.10.49
• phpstan/phpstan-beberlei-assert: ^1.1.2
• phpstan/phpstan-mockery: ^1.1.1
• phpstan/phpstan-phpunit: ^1.3.15
• phpunit/phpunit: ^10.5.3
• symfony/var-dumper: ^7.0

MIT

• Petr Chromec

README

It's basically a syntax sugar over classic array structure, which allows you to use it as classic array, but adds some cool features.

Table of Contents

• Installation
• Requirements
• Base Interfaces
  • IEnumerable
  • ICollection
  • IList
  • IMap
  • ISeq
  • ITuple
• Mutable
• Immutable
• Generic
• Arrow Functions
• Plans for next versions

Installation

composer require mf/collections-php

Requirements

• PHP ^8.2

Base Interfaces

Check out Documentation for more details.

IEnumerable

• basic Interface for enumerable
• extends IteratorAggregate, Countable
• see Immutable tuple
• see Mutable PrioritizedCollection

ICollection

• basic Interface for Collections
• extends IEnumerable
• see Mutable collections
• see Immutable collections

IList

A list is an ordered (possibly immutable) series of elements of the same type.

• extends ICollection
• see Mutable list
• see Immutable list

IMap

A map is an ordered (possibly immutable) series of key values pairs.

• extends ICollection, ArrayAccess
• see Mutable map
• see Immutable map

ISeq

A sequence is a logical series of elements all of one type.

• extends ICollection
• see Immutable seq

ITuple

A tuple is a grouping of unnamed but ordered values, possibly of different types.

• extends IEnumerable, ArrayAccess, Stringable
• see Immutable tuple

Mutable Collections

Interfaces

• Mutable\Generic\ICollection, Mutable\Generic\IList, Mutable\Generic\IMap

Mutable\Generic\ListCollection

• implements Mutable\Generic\IList
• is eager as possible

Mutable\Generic\Map

• implements Mutable\Generic\IMap
• is eager as possible

Mutable\Generic\PrioritizedCollection

• implements IEnumerable
• holds items with generic type by priority
• is eager as possible

Example of strategies by priority

For case when you want to apply only the first strategy which can do what you want. You can add strategies dynamically and still apply them by priority later.

// initialization of strategies
/** @phpstan-var PrioritizedCollection<StrategyInterface> $strategies */
$strategies = new PrioritizedCollection();
$strategies->add(new DefaultStrategy(), 1);

// added later
$strategies->add(new SpecialStrategy(), 100);

// find and apply first suitable strategy
/** @var StrategyInterface $strategy */
foreach ($strategies as $strategy) {
    if ($strategy->supports($somethingStrategic)) {
        return $strategy->apply($somethingStrategic);
    }
}

Immutable Collections

• internal state of Immutable\Collection instance will never change from the outside (it is readonly)

$list = new Immutable\ListCollection();
$listWith1 = $list->add(1);

// $list != $listWith1
echo $list->count();        // 0
echo $listWith1->count();   // 1

• $list is still an empty Immutable\ListCollection
• $listWith1 is new instance of Immutable\ListCollection with value 1

Interfaces

• Immutable\Generic\ICollection, Immutable\Generic\IList, Immutable\Generic\IMap, Immutable\Generic\ISeq, Immutable\ITuple

Immutable\Generic\ListCollection

• implements Immutable\Generic\IList
• is eager as possible

Immutable\Generic\Map

• implements Immutable\Generic\IMap
• is eager as possible

Immutable\Seq

• implements Immutable\Generic\ISeq
• is lazy as possible (even could be Infinite)

$seq = Seq::infinite()                         // 1, 2, ...
    ->filter(fn ($i) => $i % 2 === 0)   // 2, 4, ...
    ->skip(2)                           // 6, 8, ...
    ->map(fn ($i) => $i * $i)           // 36, 64, ...
    ->takeWhile(fn ($i) => $i < 100)    // 36, 64
    ->reverse()                         // 64, 36
    ->take(1);                          // 64
// for now the Sequence is still lazy

// this will generate (evaluate) the values
$array = $seq->toArray();               // [64]

Immutable\Generic\KVPair

• always has a Key and the Value
• key is restricted to int|string so it may be used in the foreach as a key
• can contain any values

Immutable\Tuple

• implements Immutable\ITuple
• must have at least 2 values (otherwise it is just a single value)
• is eager as possible
• allows destructuring, matching and parsing/formatting
• can contain any scalar values and/or arrays
  • in string representation of a Tuple, array values must be separated by ; (not by ,)

Parsing

Tuple::parse('(foo, bar)')->toArray();                  // ['foo', 'bar']
Tuple::parse('("foo, bar", boo)')->toArray();           // ['foo, bar', 'boo']
Tuple::parse('(1, "foo, bar", true)')->toArray();       // [1, 'foo, bar', true]
Tuple::parse('(1, [2; 3], [four; "Five"])')->toArray(); // [1, [2, 3], ['four', 'five']]

Matching and comparing

Tuple::from([1, 1])->match('int', 'int');                      // true
Tuple::from([1, 2, 3])->isSame(Tuple::of(1, 2, 3));            // true
Tuple::of(10, 'Foo', null)->match('int', 'string', '?string'); // true
Tuple::of(10, [9, 8])->match('int', 'array');                  // true

Parsing and matching

Tuple::parseMatch('(foo, bar)', 'string', 'string')->toArray();        // ['foo', 'bar']
Tuple::parseMatchTypes('(foo, bar)', ['string', 'string'])->toArray(); // ['foo', 'bar']

// invalid types
Tuple::parseMatch('(foo, bar, 1)', 'string', 'string'); // throws \InvalidArgumentException "Given tuple does NOT match expected types (string, string) - got (string, string, int)"

Formatting

Tuple::from([1, 'foo', null])->toString();          // '(1, "foo", null)'

// for URL
Tuple::from(['foo', 'bar'])->toStringForUrl();      // '(foo,bar)'
Tuple::from(['foo-bar', 'boo'])->toStringForUrl();  // '(foo-bar,bar)'
Tuple::from(['mail', '[e-mail]'])->toStringForUrl(); // '(mail,"[e-mail]")'

Destructuring

$tuple  = Tuple::of('first', 2, 3); // ('first', 2, 3)
$first  = $tuple->first();          // 'first'
$second = $tuple->second();         // 2
[$first, $second] = $tuple;         // $first = 'first'; $second = 2
[,, $third]       = $tuple;         // 3

Unpacking

sprintf('Title: %s | Value: %s', ...Tuple::of('foo', 'bar')); // "Title: foo | Value: bar"

Merging

• merging Tuples will automatically flat them (see last example below)

$base  = Tuple::of('one', 'two');                       // ('one', 'two')
$upTo3 = Tuple::merge($base, 'three');                  // ('one', 'two', 'three')
$upTo4 = Tuple::merge($base, '3', 'four');              // ('one', 'two', '3', 'four')
$upTo5 = Tuple::merge($base, ['3', '4'], '5');          // ('one', 'two', ['3', '4'], '5')
$upTo5 = Tuple::merge($base, Tuple::of('3', '4'), '5'); // ('one', 'two', '3', '4', '5')

Merging and matching

$base = Tuple::of('one', 'two');                                    // ('one', 'two')
$upTo3 = Tuple::mergeMatch(['string', 'string', 'int'], $base, 3);  // ('one', 'two', 3)

// invalid types
Tuple::mergeMatch(['string', 'string'], $base, 3); // throws \InvalidArgumentException "Merged tuple does NOT match expected types (string, string) - got (string, string, int)."

Sequences and lazy mapping

• if your Sequence get mapped and filtered many times (for readability), it is not a problem
  • map -> map -> filter -> map -> filter -> map will iterate the collection only once (for applying all modifiers at once)
  • this modification is done when another method is triggered, so adding new modifier is an atomic operation
• all the values are generated on the fly, so it may end on out of memory exception

Plans for next versions

• use Symfony/Stopwatch in unit tests
• even better documentation (current)