Laravel Collections

Quick Decision Guide

"Which method do I use?"

Find items:

first(fn)

firstWhere('key', 'value')

firstOrFail(fn)

sole(fn)

contains('value')

contains('key', 'value')

has('key')

every(fn)

Transform items:

map(fn)

flatMap(fn)

pluck('name')

pluck('name', 'id')

select(['id', 'name'])

mapWithKeys(fn)

keyBy('id')

mapInto(DTO::class)

Filter items:

filter(fn)

reject(fn)

where('status', 'active')

whereIn('status', ['active', 'pending'])

only(['id', 'name'])

except(['password'])

unique('email')

Group & organize:

groupBy('category')

mapToGroups(fn)

partition(fn)

keyBy('id')

chunk(100)

Aggregate:

sum('price')

avg('score')

min('price')

max('price')

reduce(fn, $initial)

countBy('type')

percentage(fn)

Combine collections:

merge($other)

concat($other)

intersect($other)

diff($other)

zip($other)

Mutability Rules

Immutable (return new collection) - almost everything:

map

filter

reject

sort

merge

pluck

unique

Mutating (modify in place, return

$this

transform

push

prepend

put

pull

pop

shift

splice

forget

// WRONG mental model:
$filtered = $collection->push('item'); // $collection IS modified

// Correct approach when you want immutability:
$new = $collection->concat(['item']); // $collection is unchanged

Common Pitfalls

1.

each()

vs

map()

vs

transform()

// each(): Side-effects, returns ORIGINAL collection
$users->each(fn($u) => $u->notify(new Welcome));

// map(): Transformation, returns NEW collection (original unchanged)
$names = $users->map(fn($u) => $u->name);

// transform(): Transformation, MUTATES original collection
$users->transform(fn($u) => $u->name); // $users is now a collection of names!

2.

pluck()

key overwrites

When using

pluck('name', 'id')

collect([
    ['id' => 1, 'name' => 'Alice'],
    ['id' => 1, 'name' => 'Bob'],   // Overwrites Alice
])->pluck('name', 'id');
// [1 => 'Bob']  -- Alice is lost!

Use

groupBy

3.

filter()

without callback removes all falsy values

collect([0, 1, '', 'hello', null, false, []])->filter()->all();
// [1, 'hello'] -- 0, '', null, false, [] are ALL removed

Use

whereNotNull()

4. N+1 queries with collection iteration

// BAD: N+1 queries
$users->each(fn($user) => $user->posts->count());

// GOOD: Eager load first
$users->load('posts');
$users->each(fn($user) => $user->posts->count());

5. Memory with large datasets

// BAD: Loads all users into memory
User::all()->each(fn($u) => process($u));

// GOOD: Constant memory with cursor
User::cursor()->each(fn($u) => process($u));

// GOOD: Chunked processing
User::chunk(1000, fn($users) => $users->each(fn($u) => process($u)));

6.

sort()

preserves keys

collect([3, 1, 2])->sort()->all();
// [1 => 1, 2 => 2, 0 => 3] -- keys preserved!

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

Higher-Order Messages

Proxy pattern for clean, concise collection operations:

// Instead of:
$users->map(function ($user) { return $user->name; });

// Write:
$users->map->name;

// Works with methods too:
$users->each->markAsVip();
$users->sum->votes;
$users->filter->isAdmin();
$users->sortBy->name;
$users->reject->isBlocked();
$users->groupBy->department;

Supported on:

average

avg

contains

each

every

filter

first

flatMap

groupBy

keyBy

map

max

min

partition

reject

skipUntil

skipWhile

some

sortBy

sortByDesc

sum

takeUntil

takeWhile

unique

Extending with Macros

Register custom collection methods (typically in a service provider's

boot

use Illuminate\Support\Collection;

Collection::macro('toUpper', function () {
    return $this->map(fn($value) => strtoupper($value));
});

// Usage
collect(['foo', 'bar'])->toUpper(); // ['FOO', 'BAR']

Reference Files

• Full method reference: See references/methods.md for every Collection method with signatures and descriptions
• LazyCollection: See references/lazy-collections.md for LazyCollection-specific methods, usage patterns, and when to choose lazy vs eager