README

Type-safe uuid collections for PHP 8.

About

This library provides flexible features to manage uuid collections (filter, factory methods, etc..) and strict clean structures.

It's based on PurrPHP Pure collections.

Inspired by Kotlin collections, the library provides three collection types:

Each type has an immutable (default) and a mutable variant (except set). Immutable methods return a new instance; mutable methods modify the instance in place and return $this.

Available Classes

Installation

composer require purrphp/uuid-collection

Usage

All UUID collection classes implement UuidCollectionInterface, which extends CollectionInterface with UUID-specific factory methods, conversion methods, and set operations.

All common code placed in UuidCollectionTrait.php.

All collections are immutable and return new object after changes.

Creating

use Purr\UuidCollection\UuidList;

// From UuidInterface objects
$list = new UuidList($uuid1, $uuid2, $uuid3);

// From UUID strings
$list = UuidList::fromStrings(
    '550e8400-e29b-41d4-a716-446655440000',
    '6ba7b810-9dad-11d1-80b4-00c04fd430c8',
);

// From raw bytes
$list = UuidList::fromBytes($bytes1, $bytes2);

// From a StringList / StringSet / StringMap
$list = UuidList::fromStringCollection($stringList);

Converting

$list->toStringArray();    // ['550e8400-...', '6ba7b810-...']
$list->toBytesArray();     // ["\x55\x0e...", ...]
$list->toInterfaceArray(); // [UuidInterface, ...]

$list->toStringList();     // StringList of UUID strings
$list->toStringSet();      // StringSet of UUID strings (unique)
$list->toStringMap();      // StringMap of UUID strings

Sorting

$sorted     = $list->sortedByValue();           // ascending (lexicographic)
$descSorted = $list->sortedByValue(desc: true); // descending

Set operations

$a = new UuidSet($uuid1, $uuid2, $uuid3);
$b = new UuidSet($uuid2, $uuid3, $uuid4);

$a->diff($b)->toStringArray();      // UUIDs in $a but not in $b → [$uuid1]
$a->intersect($b)->toStringArray(); // UUIDs present in both    → [$uuid2, $uuid3]

Adding and removing elements

$updated = $list->add($uuid4, $uuid5);    // returns new instance
$trimmed = $list->remove($uuid1, $uuid2); // returns new instance

Common Operations

All collections implement CollectionInterface from PurrPHP Pure Collection. See the full reference:

• Common Methods — searching, filtering, transforming, grouping, sizing, iteration

Development

composer install

composer test        # Run tests
composer analyse     # Static analysis
composer cs-check    # Code style check
composer cs-fix      # Fix code style
composer check       # All checks

With Docker / Make

make test       # Run tests
make analyse    # Static analysis
make cs-check   # Code style check
make check      # All checks
make shell      # Open shell in dev container

License

MIT — see LICENSE.