debuss-a/enumerable

A library that provides a fluent and expressive API for working with collections of data.

1.0.0 2025-04-27 12:55 UTC

Requires

• php: ^8.2
• ext-json: *

Requires (Dev)

• pestphp/pest: ^3.8
• phpstan/phpstan: ^2.1

MIT

• Alexandre Debusschère

• list
• collection
• enumerable

README

A library that provides an Enumerable interface and a Collection class inspired by the Enumerable class in .NET.
It offers a fluent and expressive API for working with collections of data.

Installation

Install the package via Composer:

composer require debuss-a/enumerable

Features

• Fluent and expressive API for data manipulation.
• Inspired by .NET's Enumerable class.
• Supports PHP 8.2+.
• Includes a variety of methods for filtering, transforming, and combining collections.

Usage

use Collection\Collection;

$collection = new Collection([1, 2, 3, 4, 5]);

// Example: Filter even numbers
$evenNumbers = $collection->where(fn($item) => $item % 2 === 0);

print_r($evenNumbers->toArray()); // [2, 4]

Methods

Below is a list of all available methods with examples:

Instantiation

Different ways to create a Collection:

Collection::empty(); // Creates an empty collection
Collection::repeat('hello', 3); // Creates a collection with 3 elements, all being 'hello'
Collection::fromArray([1, 2, 3]); // Creates a collection from an array
Collection::fromRange(1, 5); // Creates a collection from a range
Collection::fromJson('{"a": 1, "b": 2}'); // Creates a collection from a JSON string

all(): bool

Checks if all items match a condition.

$allEven = $collection->all(fn($item) => $item % 2 === 0);

equals(Enumerable $second): bool

Checks if two collections are equal.

$first = new Collection([1, 2, 3]);
$second = new Collection([1, 2, 3, 4, 5]);
$areEqual = $first->equals($second); // False

$second = new Collection([1, 2, 3]);
$areEqual = $first->equals($second); // True

equalBy(Enumerable $second, callable $callable): bool

Checks if two collections are equal based on a condition.

$first = Collection::fromArray([1.0, 2.0, 3.0]);
$second = Collection::fromArray([1, 2, 3]);
$areEqual = $first->equalBy($second, fn($x, $y) => (int)$x == (int)$y); // True

any(callable $callable): bool

Checks if any item matches a condition.

$collection = Collection::fromArray(['airplane', 'car']);
$any = $collection->any(fn($item) => $item == 'car')); // True

average(): int|float

Calculates the average of numeric items.

$collection = Collection::fromArray([1, 2, 3, 4, 5]);
$average = $collection->average(); // 3

max(): int|float

Returns the maximum value in the collection.

$collection = Collection::fromArray([1, 2, 3, 4, 5]);
$max = $collection->max(); // 5

min(): int|float

Returns the minimum value in the collection.

$collection = Collection::fromArray([1, 2, 3, 4, 5]);
$max = $collection->min(); // 1

sum(): int|float

Returns the sum of values in the collection.

$collection = Collection::fromArray([1, 2, 3, 4, 5]);
$max = $collection->sum(); // 15

count(): int

Returns the number of items in the collection.

$collection = Collection::fromArray([1, 2, 3, 4, 5]);
$count = $collection->count(); // 5

order(): Collection

Sorts the collection in ascending order.

$collection = Collection::fromArray([5, 3, 1, 4, 2]);
$sorted = $collection->order(); // [1, 2, 3, 4, 5]

orderBy(callable $callable): Collection

Sorts the collection based on a key generated by the callable.

$collection = Collection::fromArray(['pineapple', 'banana', 'strawberry']);
$sorted = $collection->orderBy(fn($item) => strlen($item)); // ['banana', 'pineapple', 'strawberry']

orderDescending(): Collection

Sorts the collection in descending order.

$collection = Collection::fromArray([5, 3, 1, 4, 2]);
$sorted = $collection->orderDescending(); // [5, 4, 3, 2, 1]

orderDescendingBy(callable $callable): Collection

Sorts the collection based on a key generated by the callable in descending order.

$collection = Collection::fromArray(['pineapple', 'banana', 'strawberry']);
$sorted = $collection->orderDescendingBy(fn($item) => strlen($item)); // ['strawberry', 'pineapple', 'banana']

reverse(): Collection

Reverses the order of items in the collection.

$collection = Collection::fromArray([1, 2, 3, 4, 5]);
$reversed = $collection->reverse(); // [5, 4, 3, 2, 1]

append(mixed $item): Collection

Adds an item to the end of the collection.

$collection = Collection::fromArray([1, 2, 3]);
$collection = $collection->append(4);
print_r($collection->toArray()); // [1, 2, 3, 4]

prepend(mixed $item): Collection

Adds an item to the beginning of the collection.

$collection = Collection::fromArray([1, 2, 3]);
$collection = $collection->prepend(0);
print_r($collection->toArray()); // [0, 1, 2, 3]

chunk(int $length): Collection

Splits the collection into chunks of a specified length.

$collection = Collection::fromArray([1, 2, 3, 4, 5]);
$chunks = $collection->chunk(2);
print_r($chunks->toArray()); // [[1, 2], [3, 4], [5]]

concat(Enumerable $second): Collection

Concatenates two collections.

$other = new Collection([6, 7, 8]);
$concatenated = $collection->concat($other);
print_r($concatenated->toArray()); // [1, 2, 3, 4, 5, 6, 7, 8]

contains(mixed $item): bool

Checks if the collection contains a specific item.

$collection = Collection::fromArray([1, 2, 3]);
$contains = $collection->contains(2); // True

countBy(callable $callable): int

Counts the number of items that match a condition.

$collection = Collection::fromArray([1, 2, 3, 4, 5]);
$count = $collection->countBy(fn($item) => $item > 2); // 3

distinct(): Collection

Returns a new collection with distinct items.

$collection = Collection::fromArray([1, 2, 2, 3, 4, 4]);
$distinct = $collection->distinct();
print_r($distinct->toArray()); // [1, 2, 3, 4]

distinctBy(callable $callable): Collection

Returns a new collection with distinct items based on a key generated by the callable.

$collection = Collection::fromArray(['apple', 'banana', 'apple', 'orange']);
$distinct = $collection->distinctBy(fn($item) => $item[0]);
print_r($distinct->toArray()); // ['apple', 'banana', 'orange']

itemAt(int $index): mixed

Returns the item at a specific index.

$collection = Collection::fromArray([1, 2, 3, 4, 5]);
$item = $collection->itemAt(2); // 3

itemAtOrDefault(int $index, mixed $default = null): mixed

Returns the item at a specific index or a default value if the index is out of bounds.

$collection = Collection::fromArray([1, 2, 3, 4, 5]);
$item = $collection->itemAtOrDefault(10, 'not found'); // 'not found'

except(Enumerable $items): Collection

Returns a new collection excluding the specified items.

$collection = Collection::fromArray([1, 2, 3, 4, 5]);
$other = new Collection([2, 3]);
$except = $collection->except($other);
print_r($except->toArray()); // [1, 4, 5]

intersect(Enumerable $items): Collection

Returns the intersection of two collections.

$other = new Collection([3, 4, 5, 6]);
$intersection = $collection->intersect($other);
print_r($intersection->toArray()); // [3, 4, 5]

first(): mixed

Returns the first item in the collection.

$collection = Collection::fromArray([1, 2, 3, 4, 5]);
echo $collection->first(); // 1

firstOrDefault(mixed $default = null): mixed

Returns the first item or a default value if the collection is empty.

$collection = Collection::empty();
echo $collection->firstOrDefault(1); // 1

last(): mixed

Returns the last item in the collection.

$collection = Collection::fromArray([1, 2, 3, 4, 5]);
echo $collection->last(); // 5

lastOrDefault(mixed $default = null): mixed

Returns the last item or a default value if the collection is empty.

$collection = Collection::empty();
echo $collection->lastOrDefault(5); // 5

select(callable $callable): Collection

Projects each item into a new form.

$collection = Collection::fromArray([1, 2, 3]);
$squared = $collection->select(fn($item) => $item * 2);
print_r($squared->toArray()); // [2, 4, 6]

single(callable $callable): mixed

Returns the single item that matches the condition.

$collection = Collection::fromArray([1, 2, 3]);
echo $collection->single(fn($item) => $item === 3); // 3

singleOrDefault(callable $callable, mixed $default = null): mixed

Returns the single item that matches the condition or a default value.

$collection = Collection::fromArray([1, 2, 3]);
echo $collection->singleOrDefault(fn($item) => $item === 6, 'not found'); // not found

skip(int $count): Collection

Skips the first $count items.

$collection = Collection::fromArray([1, 2, 3, 4, 5]);
$skipped = $collection->skip(2);
print_r($skipped->toArray()); // [3, 4, 5]

skipLast(int $count): Collection

Skips the last $count items.

$collection = Collection::fromArray([1, 2, 3, 4, 5]);
$skippedLast = $collection->skipLast(2);
print_r($skippedLast->toArray()); // [1, 2, 3]

skipWhile(callable $callable): Collection

Skips items while the condition is true.

$collection = Collection::fromArray([1, 2, 3, 4, 5]);
$skippedWhile = $collection->skipWhile(fn($item) => $item < 3);
print_r($skippedWhile->toArray()); // [3, 4, 5]

take(int $count): Collection

Takes the first $count items.

$collection = Collection::fromArray([1, 2, 3, 4, 5]);
$taken = $collection->take(3);
print_r($taken->toArray()); // [1, 2, 3]

takeLast(int $count): Collection

Takes the last $count items.

$collection = Collection::fromArray([1, 2, 3, 4, 5]);
$takenLast = $collection->takeLast(2);
print_r($takenLast->toArray()); // [4, 5]

takeWhile(callable $callable): Collection

Takes items while the condition is true.

$collection = Collection::fromArray([1, 2, 3, 4, 5]);
$takenWhile = $collection->takeWhile(fn($item) => $item < 4);
print_r($takenWhile->toArray()); // [1, 2, 3]

union(Enumerable $second): Collection

Combines two collections and removes duplicates.

$collection = Collection::fromArray([1, 2, 3, 4, 5]);
$other = new Collection([4, 5, 6]);
$union = $collection->union($other);
print_r($union->toArray()); // [1, 2, 3, 4, 5, 6]

where(callable $callable): Collection

Filters items based on a condition.

$collection = Collection::fromArray([1, 2, 3, 4, 5]);
$filtered = $collection->where(fn($item) => $item > 3);
print_r($filtered->toArray()); // [4, 5]

zip(Enumerable $second, callable $callable): Collection

Combines two collections into one using a callable.

$collection = Collection::fromArray([1, 2, 3]);
$other = new Collection(['a', 'b', 'c']);
$zipped = $collection->zip($other, fn($a, $b) => $a.$b);
print_r($zipped->toArray()); // ['1a', '2b', '3c']

toArray(): array

Converts the collection to an array.

print_r($collection->toArray()); // [1, 2, 3, 4, 5]

License

This project is licensed under the MIT License. See the LICENSE.md file for details.