fyre/collection

A collection library.

v1.0.4 2024-10-30 10:55 UTC

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.59
• fyre/php-cs-fixer-config: ^1.0
• phpunit/phpunit: ^11

MIT

• elusivecodes

README

FyreCollection is a free, open-source immutable collection library for PHP.

It is a modern library, and features support for generators and lazy evaluation.

Table Of Contents

• Installation
• Basic Usage
• Collection Creation
• Methods

Installation

Using Composer

composer require fyre/collection

In PHP:

use Fyre\Collection\Collection;

Basic Usage

• $source can be either an array, a Closure that returns a Generator, or a Traversable or JsonSerializable object.

$collection = new Collection($source);

The Collection is an implementation of an Iterator and can be used in a foreach loop.

foreach ($collection AS $key => $value) { }

Collection Creation

Empty

Create an empty collection.

$collection = Collection::empty();

Range

Create a collection for a range of numbers.

• $from is an integer representing the start of the range.
• $to is an integer representing the end of the range.

$collection = Collection::range($from, $to);

Methods

Avg

Get the average value of a key.

• $valuePath is a string or array representing the path to the value, or a Closure that receives the item and key as arguments, and should return the value, and will default to null.

$avg = $collection->avg($valuePath);

Cache

Cache the computed values via a new collection.

$cache = $collection->cache();

Chunk

Split the collection into chunks.

• $size is a number representing the size of each chunk.
• $preserveKey is a boolean indicating whether to preserve the keys, and will default to false.

$chunk = $collection->chunk($size, $preserveKeys);

Collect

Collect the computed values into a new collection.

$collect = $collection->collect();

Combine

Re-index the items in the collection by a given key, using a given value.

• $keyPath is a string or array representing the path to the new key, or a Closure that receives the item and key as arguments, and should return the new key.
• $valuePath is a string or array representing the path to the value, or a Closure that receives the item and key as arguments, and should return the value.

$combine = $collection->combine($keyPath, $valuePath);

Count

Count all items in the collection.

$count = $collection->count();

Count By

Groups the items in the collection by a given key, and count the number of items in each.

• $keyPath is a string or array representing the path to the group key, or a Closure that receives the item and key as arguments, and should return the group key.

$countBy = $collection->countBy($keyPath);

Dot

Flatten a multi-dimensional collection using "dot" notation.

$dot = $collection->dot();

Each

Execute a callback on each item in the collection.

• $callback is a Closure that receives the item and key as arguments.

$collection->each($callback);

Every

Determine whether every item in the collection passes a callback.

• $callback is a Closure that receives the item and key as arguments, and should return a boolean.

$every = $collection->every($callback);

Except

Return a collection without the specified keys.

• $keys is an array containing the keys to remove.

$except = $collection->except($callback);

Extract

Extract values from the collection using "dot" notation.

• $valuePath is a string or array representing the path to the value, or a Closure that receives the item and key as arguments, and should return the value.

$extract = $collection->extract($valuePath);

Filter

Filter items in the collection using a callback function.

• $callback is a Closure that receives the item and key as arguments, and should return a boolean.

$filter = $collection->filter($callback);

Find

Find the first value in the collection that passes a callback.

• $callback is a Closure that receives the item and key as arguments, and should return a boolean.

$find = $collection->find($callback);

Find Last

Find the last value in the collection that passes a callback.

• $callback is a Closure that receives the item and key as arguments, and should return a boolean.

$findLast = $collection->findLast($callback);

First

Get the first value in the collection.

$first = $collection->first();

Flatten

Flatten a multi-dimensional collection into a single level.

• $maxDepth is a number representing the maximum depth to flatten, and will default to PHP_INT_MAX.

$flatten = $collection->flattened($maxDepth);

Flip

Swap the keys and values of a collection.

$flip = $collection->flip();

Group By

Group the items in the collection by a given key.

• $keyPath is a string or array representing the path to the new key, or a Closure that receives the item and key as arguments, and should return the new key.

$groupBy = $collection->groupBy($keyPath);

Includes

Determine whether a given value exists in the collection.

• $value is the value to test for.

$includes = $collection->includes($value);

Index By

Re-index the items in the collection by a given key.

• $keyPath is a string or array representing the path to the new key, or a Closure that receives the item and key as arguments, and should return the new key.

$indexBy = $collection->indexBy($keyPath);

Index Of

Search the collection for a given value and return the first key.

• $value is the value to test for.

$indexOf = $collection->indexOf($value);

Is Empty

Determine whether the collection is empty.

$isEmpty = $collection->isEmpty();

Join

Join the items in the collection using a specified separator.

• $glue is a string representing the separator to join with.
• $finalGlue is a string representing the final separator to join with, and will default to null.

$join = $collection->join($glue, $finalGlue);

Keys

Get the keys in the collection.

$keys = $collection->keys();

Last

Get the last value in the collection.

$last = $collection->last();

Last Index Of

Search the collection for a given value and return the last key.

• $value is the value to test for.

$lastIndexOf = $collection->lastIndexOf($value);

List Nested

Flatten nested items into a list.

• $order is a string representing the order, and will default to "desc".
• $nestingKey is a string representing the nesting key, and will default to "children".

$listNested = $collection->listNested($order, $nestingKey);

Map

Apply a callback to the items in the collection.

• $callback is a Closure that receives the item and key as arguments, and should return the new value.

$map = $collection->map($callback);

Max

Get the maximum value of a key.

• $valuePath is a string or array representing the path to the value, or a Closure that receives the item and key as arguments, and should return the value, and will default to null.

$max = $collection->max($valuePath);

Median

Get the median value of a key.

• $valuePath is a string or array representing the path to the value, or a Closure that receives the item and key as arguments, and should return the value, and will default to null.

$median = $collection->median($valuePath);

Merge

Merge one or more iterables into the collection.

All arguments supplied must be either an array or Iterator, and will be merged with the collection.

$merge = $collection->merge(...$iterables);

Min

Get the minimum value of a key.

• $valuePath is a string or array representing the path to the value, or a Closure that receives the item and key as arguments, and should return the value, and will default to null.

$min = $collection->min($valuePath);

Nest

Nest child items inside parent items.

• $idPath is a string or array representing the path to the ID, or a Closure that receives the item and key as arguments, and should return the ID, and will default to "id".
• $parentPath is a string or array representing the path to the parent ID, or a Closure that receives the item and key as arguments, and should return the parent ID, and will default to "id".
• $nestingKey is a string representing the nesting key, and will default to "children".

$nest = $collection->nest($idPath, $parentPath, $nestingKey);

None

Determine whether no items in the collection pass a callback.

• $callback is a Closure that receives the item and key as arguments, and should return a boolean.

$none = $collection->none($callback);

Only

Return a Collection with only the specified keys.

• $keys is an array containing the keys to include.

$only = $collection->only($callback);

Print Nested

Format nested list items based on depth.

• $valuePath is a string or array representing the path to the value, or a Closure that receives the item and key as arguments, and should return the value, and will default to "id".
• $idPath is a string or array representing the path to the ID, or a Closure that receives the item and key as arguments, and should return the ID, and will default to "id".
• $nestingKey is a string representing the nesting key, and will default to "children".

$printNested = $collection->printNested($valuePath, $idPath, $prefix, $nestingKey);

Random Value

Pull a random item out of the collection.

$randomValue = $collection->randomValue();

Reduce

Iteratively reduce the collection to a single value using a callback function.

• $callback is a Closure that receives the accumulated value, item and key as arguments, and should return the next value.
• $initial is the initial value to use, and will default to null.

$reduce = $collection->reduce($callback, $initial);

Reject

Exclude items in the collection using a callback function.

• $callback is a Closure that receives the item and key as arguments, and should return a boolean.

$reject = $collection->reject($callback);

Reverse

Reverse the order of items in the collection.

$reverse = $collection->reverse();

Shuffle

Randomize the order of items in the collection.

$shuffle = $collection->shuffle();

Skip

Skip a number of items in the collection.

• $length is a number representing the number of items to skip.

$skip = $collection->skip($length);

Skip Until

Skip items in the collection until a callback returns true.

• $callback is a Closure that receives the item and key as arguments, and should return a boolean.

$skipUntil = $collection->skipUntil($callback);

Skip While

Skip items in the collection until a callback returns false.

• $callback is a Closure that receives the item and key as arguments, and should return a boolean.

$skipWhile = $collection->skipWhile($callback);

Some

Determine whether some items in the collection pass a callback.

• $callback is a Closure that receives the item and key as arguments, and should return a boolean.

$some = $collection->some($callback);

Sort

Sort the collection using a callback.

• $callback is a Closure that receives 2 items to compare, and should return an integer to determine the sort order.

$sort = $collection->sort($callback);

Alternatively, you can sort the collection items in ascending order.

• $sort is a number representing the sorting flag, and will default to Collection::SORT_NATURAL.

$sort = $collection->sort($sort);

Sort By

Sort the collection by a given key.

• $valuePath is a string or array representing the path to the value, or a Closure that receives the item and key as arguments, and should return the value, and will default to null.
• $sort is a number representing the sorting flag, and will default to Collection::SORT_NATURAL.
• $descending is a boolean indicating whether to sort in descending order, and will default to false.

$sortBy = $collection->sortBy($valuePath, $sort, $descending);

Sum Of

Get the total sum of a key.

• $valuePath is a string or array representing the path to the value, or a Closure that receives the item and key as arguments, and should return the value, and will default to null.

$sumOf = $collection->sumOf($valuePath);

Take

Take a number of items in the collection.

• $length is a number representing the number of items to skip.

$take = $collection->take($length);

Take Until

Take items in the collection until a callback returns true.

• $callback is a Closure that receives the item and key as arguments, and should return a boolean.

$takeUntil = $collection->takeUntil($callback);

Take While

Take items in the collection until a callback returns false.

• $callback is a Closure that receives the item and key as arguments, and should return a boolean.

$takeWhile = $collection->takeWhile($callback);

To Array

Get the items in the collection as an array.

$array = $collection->toArray();

To Json

$json = $collection->toJson();

To List

Get the values in the collection as an array.

$list = $collection->toList();

Unique

Get the unique items in the collection based on a given key.

• $valuePath is a string or array representing the path to the value, or a Closure that receives the item and key as arguments, and should return the value, and will default to null.
• $strict is a boolean indicating whether to perform strict equality checks, and will default to false.

$unique = $collection->unique($valuePath, $strict);

Values

Get the values in the collection.

$values = $collection->values();

Zip

Zip one or more iterables with the collection.

All arguments supplied must be either an array or Iterator, and will be zipped with the collection.

$zip = $collection->zip(...$iterables);