Skip to content

collection.md

Latest commit

 

History

History
532 lines (417 loc) · 14.5 KB

collection.md

File metadata and controls

532 lines (417 loc) · 14.5 KB
Raw

Collection

Fluent, chainable wrapper around arrays. Namespace Zero\Lib\Support\Collection (aliased as Collection). Build with the global collect() helper or Collection::make().

use Zero\Lib\Support\Collection;

collect([1, 2, 3, 4, 5])
    ->filter(fn ($v) => $v > 2)
    ->map(fn ($v) => $v * 10)
    ->values()
    ->all(); // [30, 40, 50]

Collection implements ArrayAccess, Countable, IteratorAggregate, JsonSerializable, so count($c), foreach ($c as ...), $c[$key], and json_encode($c) work directly.

Topics: Building · Conversion · Iteration · Filtering · Querying · Mutation · Slicing · Reshaping · Set Operations · Sorting · Aggregates · Conditional

Building

Static factories on Collection. Implementation: top of Collection.php.

collect(mixed $items = []): Collection / Collection::make(iterable $items)

collect([1, 2, 3])->count();                // 3
Collection::make(['a' => 1])->all();        // ['a' => 1]

Collection::wrap(mixed $value): Collection

Wrap any value.

Collection::wrap('a')->all(); // ['a']
Collection::wrap(null)->all(); // []

Collection::range(int $from, int $to): Collection

Collection::range(1, 3)->all(); // [1, 2, 3]

Collection::times(int $number, ?callable $callback = null): Collection

Collection::times(3, fn ($i) => $i * 2)->all(); // [2, 4, 6]

Conversion

Implementation: Concerns/Collection/Conversion.php.

all(): array

collect([1, 2, 3])->all(); // [1, 2, 3]

toArray(): array

Recursively convert nested Collections / JsonSerializable.

collect([collect([1, 2])])->toArray(); // [[1, 2]]

toJson(int $flags = 0): string / jsonSerialize(): array

collect([1, 2])->toJson();              // '[1,2]'
json_encode(collect([1, 2]));           // '[1,2]'

count(): int / isEmpty(): bool / isNotEmpty(): bool

collect([1, 2])->count();         // 2
collect([])->isEmpty();           // true
collect([1])->isNotEmpty();       // true
count(collect([1, 2, 3]));        // 3

keys(): Collection / values(): Collection

collect(['a' => 1, 'b' => 2])->keys()->all();   // ['a', 'b']
collect(['a' => 1, 'b' => 2])->values()->all(); // [1, 2]

ArrayAccess / getIterator()

$c = collect(['a' => 1]);
$c['a'];                // 1
foreach ($c as $k => $v) { /* ... */ }

Iteration

Implementation: Concerns/Collection/Iteration.php.

map(callable $cb): Collection

collect([1, 2, 3])->map(fn ($v) => $v * 2)->all(); // [2, 4, 6]

mapWithKeys(callable $cb): Collection

collect([['id' => 1, 'n' => 'a']])
    ->mapWithKeys(fn ($v) => [$v['id'] => $v['n']])
    ->all(); // [1 => 'a']

mapSpread(callable $cb): Collection

Spread each item's values as positional arguments.

collect([[1, 2], [3, 4]])
    ->mapSpread(fn ($a, $b) => $a + $b)
    ->all(); // [3, 7]

flatMap(callable $cb): Collection

Map then collapse.

collect([[1, 2], [3]])->flatMap(fn ($v) => $v)->all(); // [1, 2, 3]

each(callable $cb): self

Iterate; return false from the callback to stop.

collect([1, 2, 3])->each(function ($v) { /* side effect */ });

eachSpread(callable $cb): self

collect([[1, 2], [3, 4]])->eachSpread(fn ($a, $b) => /* ... */);

reduce(callable $cb, $initial = null): mixed

collect([1, 2, 3])->reduce(fn ($carry, $v) => $carry + $v, 0); // 6

pluck(string|array|null $value, $key = null): Collection

collect([['id' => 1], ['id' => 2]])->pluck('id')->all(); // [1, 2]

partition(callable $cb): Collection

Returns a Collection of two Collections.

[$evens, $odds] = collect([1, 2, 3, 4])->partition(fn ($v) => $v % 2 === 0);
$evens->all(); // [1 => 2, 3 => 4]
$odds->all();  // [0 => 1, 2 => 3]

keyBy(callable|string $keyBy): Collection

collect([['id' => 1], ['id' => 2]])->keyBy('id')->keys()->all(); // [1, 2]

groupBy(callable|string $groupBy): Collection

Each group is itself a Collection.

collect([['t' => 'a'], ['t' => 'a'], ['t' => 'b']])
    ->groupBy('t')
    ->count(); // 2

Filtering

Implementation: Concerns/Collection/Filtering.php.

filter(?callable $cb = null): Collection

Without a callback, drops falsy values.

collect([0, 1, 2])->filter()->values()->all();                  // [1, 2]
collect([1, 2, 3, 4])->filter(fn ($v) => $v > 2)->values()->all(); // [3, 4]

reject(callable $cb): Collection

Inverse of filter.

collect([1, 2, 3, 4])->reject(fn ($v) => $v % 2 === 0)->values()->all(); // [1, 3]

where(string $key, $operator = null, $value = null): Collection

Two-argument form is =. Operators: =, ==, ===, !=, !==, <>, >, >=, <, <=.

$users = [['active' => true], ['active' => false]];
collect($users)->where('active', true)->count(); // 1
collect([['n' => 5], ['n' => 1]])->where('n', '>', 3)->count(); // 1

whereIn(string $key, iterable $values): Collection / whereNotIn(...)

collect([['t' => 'a'], ['t' => 'b'], ['t' => 'c']])
    ->whereIn('t', ['a', 'c'])
    ->count(); // 2

whereNotNull(?string $key = null): Collection / whereNull(...)

collect([1, null, 2])->whereNotNull()->values()->all(); // [1, 2]
collect([['n' => 1], ['n' => null]])->whereNull('n')->count(); // 1

only(array|string $keys): Collection / except(...)

collect(['a' => 1, 'b' => 2, 'c' => 3])->only(['a', 'c'])->all(); // ['a' => 1, 'c' => 3]

contains($key, $operator = null, $value = null): bool

Scalar / closure / where form.

collect([1, 2, 3])->contains(2);                    // true
collect([1, 2, 3])->contains(fn ($v) => $v > 2);    // true
collect([['t' => 'a']])->contains('t', 'a');        // true

has(string|int|array $key): bool

Returns true only when every key exists.

collect(['a' => 1])->has('a');               // true
collect(['a' => 1])->has(['a', 'b']);        // false

Querying

Implementation: Concerns/Collection/Querying.php.

first(?callable $cb = null, $default = null): mixed / last(...)

collect([1, 2, 3])->first();                          // 1
collect([1, 2, 3])->first(fn ($v) => $v > 1);         // 2
collect([1, 2, 3])->last();                           // 3

get(string|int $key, $default = null): mixed

collect(['a' => 1])->get('a');                  // 1
collect([])->get('x', 'fallback');              // 'fallback'

search(mixed $value, bool $strict = false): mixed

Returns the matching key (or false). Accepts a closure.

collect(['a', 'b', 'c'])->search('b');                 // 1
collect([1, 2, 3])->search(fn ($v) => $v === 2);       // 1

random(?int $number = null, bool $preserveKeys = false): mixed

collect([1, 2, 3, 4, 5])->random();      // single item
collect([1, 2, 3, 4, 5])->random(3);     // Collection of 3 items

Mutation

These mutate the underlying items in place and return $this. Implementation: Concerns/Collection/Mutation.php.

put(string|int $key, mixed $value): self

collect()->put('a', 1)->all(); // ['a' => 1]

pull(string|int $key, $default = null): mixed

Read and remove.

$c = collect(['a' => 1, 'b' => 2]);
$c->pull('a'); // 1; $c->all() === ['b' => 2]

push(mixed ...$values): self

collect([1])->push(2, 3)->all(); // [1, 2, 3]

prepend(mixed $value, $key = null): self

collect([2, 3])->prepend(1)->all();        // [1, 2, 3]
collect(['b' => 2])->prepend(1, 'a')->all(); // ['a' => 1, 'b' => 2]

pop(int $count = 1): mixed / shift(int $count = 1): mixed

With $count = 1 returns the item; otherwise returns a Collection.

collect([1, 2, 3])->pop();    // 3
collect([1, 2, 3])->shift();  // 1

forget(string|int|array $keys): self

collect(['a' => 1, 'b' => 2])->forget('a')->all(); // ['b' => 2]

Slicing

Implementation: Concerns/Collection/Slicing.php.

take(int $limit): Collection

collect([1, 2, 3, 4])->take(2)->all();   // [1, 2]
collect([1, 2, 3, 4])->take(-2)->all();  // [3, 4]

skip(int $count): Collection

collect([1, 2, 3, 4])->skip(2)->values()->all(); // [3, 4]

slice(int $offset, ?int $length = null): Collection

collect([1, 2, 3, 4])->slice(1, 2)->values()->all(); // [2, 3]

chunk(int $size): Collection

Returns a Collection of Collections.

collect([1, 2, 3, 4, 5])->chunk(2)->count(); // 3

nth(int $step, int $offset = 0): Collection

collect([1, 2, 3, 4, 5, 6])->nth(2)->all();    // [1, 3, 5]
collect([1, 2, 3, 4, 5, 6])->nth(2, 1)->all(); // [2, 4, 6]

Reshaping

Implementation: Concerns/Collection/Reshaping.php.

collapse(): Collection

Merge a list of arrays.

collect([[1, 2], [3]])->collapse()->all(); // [1, 2, 3]

flatten(int $depth = PHP_INT_MAX): Collection

collect([1, [2, [3]]])->flatten()->all(); // [1, 2, 3]

flip(): Collection

collect(['a', 'b'])->flip()->all(); // ['a' => 0, 'b' => 1]

dot(): Collection / undot(): Collection

collect(['a' => ['b' => 1]])->dot()->all(); // ['a.b' => 1]
collect(['a.b' => 1])->undot()->all();      // ['a' => ['b' => 1]]

reverse(): Collection

Preserves keys.

collect([1, 2, 3])->reverse()->values()->all(); // [3, 2, 1]

zip(iterable ...$items): Collection

collect([1, 2])->zip([3, 4])->first()->all(); // [1, 3]

Set Operations

Implementation: Concerns/Collection/SetOperations.php.

merge(iterable $items): Collection / mergeRecursive(iterable $items): Collection

collect([1, 2])->merge([3, 4])->all(); // [1, 2, 3, 4]

concat(iterable $source): Collection

Append numerically (no key collision).

collect([1, 2])->concat([3])->all(); // [1, 2, 3]

combine(iterable $values): Collection

Use this collection's values as keys, combine with $values.

collect(['a', 'b'])->combine([1, 2])->all(); // ['a' => 1, 'b' => 2]

diff(iterable $items): Collection / diffKeys(iterable $items): Collection

collect([1, 2, 3])->diff([2])->values()->all(); // [1, 3]

intersect(iterable $items): Collection / intersectByKeys(iterable $items): Collection

collect([1, 2, 3])->intersect([2, 3, 4])->values()->all(); // [2, 3]

Sorting

Implementation: Concerns/Collection/Sorting.php.

sort(?callable $cb = null): Collection

collect([3, 1, 2])->sort()->values()->all(); // [1, 2, 3]

sortBy(callable|string $cb, int $options = SORT_REGULAR, bool $descending = false): Collection

collect([['n' => 3], ['n' => 1]])
    ->sortBy('n')
    ->values()
    ->pluck('n')
    ->all(); // [1, 3]

sortByDesc(callable|string $cb, int $options = SORT_REGULAR): Collection

collect([['n' => 1], ['n' => 3]])->sortByDesc('n')->values()->pluck('n')->all(); // [3, 1]

sortDesc(): Collection

Without a key/callback.

collect([1, 3, 2])->sortDesc()->values()->all(); // [3, 2, 1]

sortKeys(int $options = SORT_REGULAR, bool $descending = false): Collection

collect(['b' => 1, 'a' => 2])->sortKeys()->keys()->all(); // ['a', 'b']

unique(callable|string|null $key = null, bool $strict = false): Collection

collect([1, 2, 2, 3])->unique()->values()->all(); // [1, 2, 3]
collect([['t' => 'a'], ['t' => 'a'], ['t' => 'b']])->unique('t')->count(); // 2

duplicates(): Collection

Items that appear more than once.

collect([1, 2, 2, 3, 3])->duplicates()->count(); // 4

shuffle(?int $seed = null): Collection

Seedable.

collect([1, 2, 3])->shuffle()->count(); // 3

Aggregates

Implementation: Concerns/Collection/Aggregates.php.

sum(callable|string|null $cb = null): int|float

collect([1, 2, 3])->sum();                          // 6
collect([['n' => 1], ['n' => 2]])->sum('n');        // 3

avg(callable|string|null $cb = null): int|float|null (alias average)

collect([1, 2, 3, 4])->avg(); // 2.5

min(callable|string|null $cb = null): mixed / max(...)

collect([3, 1, 2])->min(); // 1
collect([3, 1, 2])->max(); // 3

median(callable|string|null $cb = null): int|float|null

collect([1, 2, 3])->median();    // 2
collect([1, 2, 3, 4])->median(); // 2.5

implode(string $glue, ?string $key = null): string

collect(['a', 'b', 'c'])->implode(',');                  // 'a,b,c'
collect([['n' => 'a'], ['n' => 'b']])->implode(',', 'n'); // 'a,b'

join(string $glue, string $finalGlue = ''): string

collect(['a', 'b', 'c'])->join(', ', ' and '); // 'a, b and c'

Conditional

Implementation: Concerns/Collection/Conditional.php.

pipe(callable $cb): mixed

Forward the Collection through a callback.

collect([1, 2, 3])->pipe(fn ($c) => $c->sum()); // 6

tap(callable $cb): self

Side effect; returns the Collection.

collect([1, 2])->tap(fn ($c) => logger("count={$c->count()}"))->count(); // 2

when(mixed $cond, callable $cb, ?callable $default = null): self

Run $cb only when $cond is truthy.

collect([1, 2])->when(true, fn ($c) => $c->push(3))->all(); // [1, 2, 3]

unless(mixed $cond, callable $cb, ?callable $default = null): self

collect([1])->unless(false, fn ($c) => $c->push(2))->all(); // [1, 2]

whenEmpty(callable $cb, ?callable $default = null): self / whenNotEmpty(...)

collect([])->whenEmpty(fn ($c) => $c->push(1))->all();    // [1]
collect([1])->whenNotEmpty(fn ($c) => $c->push(2))->all(); // [1, 2]