Table Of Contents
- Introduction to Laravel Collections
- Collections: More Than Just Arrays
- Creating and Converting Collections
- Advanced Collection Methods
- Collection Pipelines and Method Chaining
- Higher-Order Messages: Shorthand Syntax
- LazyCollection: For Working with Large Datasets
- Custom Collections
- Performance Considerations
- Real-World Collection Recipes
- Testing Collection Code
- Extending Collections with Macros
- Collections and Functional Programming
- Conclusion
Introduction to Laravel Collections
Data manipulation is at the heart of most web applications. Whether you're filtering user records, transforming API responses, or aggregating analytics data, working with arrays and collections of items is a daily task for most developers.
Laravel Collections are one of the framework's most powerful features, yet many developers only scratch the surface of what they can do. They provide an elegant, object-oriented interface for working with arrays of data, with dozens of methods that transform messy, procedural code into clean, descriptive chains of operations.
Related:
In this comprehensive guide, we'll explore the more advanced aspects of Laravel Collections, moving beyond the basics to understand their internal workings, performance characteristics, and how to leverage them to write more expressive, maintainable code.
Collections: More Than Just Arrays
At its core, a Laravel Collection is a wrapper around a PHP array that provides a fluent, chainable interface for manipulating that array. While PHP's array functions are powerful, they have inconsistent parameter ordering, confusing return values, and require verbose, procedural code.
Consider this simple example:
// Using PHP arrays
$users = [
['name' => 'John', 'active' => true],
['name' => 'Jane', 'active' => false],
['name' => 'Dave', 'active' => true],
];
$activeUserNames = array_map(
function ($user) {
return $user['name'];
},
array_filter($users, function ($user) {
return $user['active'];
})
);
// Using Laravel Collections
$activeUserNames = collect($users)
->filter(function ($user) {
return $user['active'];
})
->map(function ($user) {
return $user['name'];
})
->values();
The Collection approach is not only more readable but also more maintainable and less prone to errors. The methods chain together in the order you think about the operations, rather than nesting function calls inside out.
Creating and Converting Collections
Creating Collections
There are several ways to create collections:
// From the helper function
$collection = collect([1, 2, 3]);
// From the constructor
$collection = new Collection([1, 2, 3]);
// From Eloquent
$users = User::all(); // Returns a Collection
// From an existing collection
$newCollection = $collection->map(function ($item) {
return $item * 2;
});
Converting Collections
Collections can be converted to various formats:
$array = $collection->all(); // or ->toArray()
$json = $collection->toJson();
$string = $collection->join(', ');
$queryString = $collection->query(); // For key-value collections
$items = $collection->values(); // Reset keys
Advanced Collection Methods
See also:
Let's explore some of the more powerful but less commonly used collection methods:
Data Transformation
transform()
Modifies the collection in place, unlike map() which returns a new collection:
$collection = collect([1, 2, 3]);
$collection->transform(function ($item) {
return $item * 2;
});
// $collection now contains [2, 4, 6]
flatMap()
Maps a collection and flattens the result:
$collection = collect([
['name' => 'John', 'hobbies' => ['Cycling', 'Reading']],
['name' => 'Jane', 'hobbies' => ['Swimming', 'Dancing']],
]);
$hobbies = $collection->flatMap(function ($person) {
return $person['hobbies'];
});
// ['Cycling', 'Reading', 'Swimming', 'Dancing']
keyBy()
Keys the collection by the given key:
$collection = collect([
['id' => 123, 'name' => 'John'],
['id' => 456, 'name' => 'Jane'],
]);
$keyed = $collection->keyBy('id');
// [
// 123 => ['id' => 123, 'name' => 'John'],
// 456 => ['id' => 456, 'name' => 'Jane'],
// ]
Advanced Filtering
whereInstanceOf()
Filters items by class:
$collection = collect([
new User,
new Post,
new User,
]);
$users = $collection->whereInstanceOf(User::class);
whereNotNull()
Removes null values for a specific key:
$collection = collect([
['name' => 'John', 'email' => 'john@example.com'],
['name' => 'Jane', 'email' => null],
]);
$withEmail = $collection->whereNotNull('email');
when()
Conditionally apply a callback:
$collection = collect([1, 2, 3]);
$collection->when($someCondition, function ($collection) {
return $collection->filter(function ($value) {
return $value > 1;
});
});
Collection Comparison
diff() and intersect()
Find differences and similarities between collections:
$collection1 = collect([1, 2, 3, 4, 5]);
$collection2 = collect([2, 4, 6, 8]);
$diff = $collection1->diff($collection2); // [1, 3, 5]
$intersect = $collection1->intersect($collection2); // [2, 4]
diffAssoc() and intersectByKeys()
Compare arrays with associative keys:
$collection1 = collect(['color' => 'red', 'size' => 'M', 'material' => 'cotton']);
$collection2 = collect(['color' => 'blue', 'size' => 'M', 'price' => 20]);
$diffAssoc = $collection1->diffAssoc($collection2);
// ['color' => 'red', 'material' => 'cotton']
$intersectByKeys = $collection1->intersectByKeys($collection2);
// ['color' => 'red', 'size' => 'M']
Grouping and Chunking
groupBy()
Group items by a key:
$collection = collect([
['department' => 'Sales', 'name' => 'John'],
['department' => 'IT', 'name' => 'Jane'],
['department' => 'Sales', 'name' => 'Dave'],
]);
$byDepartment = $collection->groupBy('department');
// [
// 'Sales' => [
// ['department' => 'Sales', 'name' => 'John'],
// ['department' => 'Sales', 'name' => 'Dave'],
// ],
// 'IT' => [
// ['department' => 'IT', 'name' => 'Jane'],
// ],
// ]
chunkWhile()
Chunk items based on a callback:
$collection = collect(str_split('AABBCCCD'));
$chunks = $collection->chunkWhile(function ($value, $key, $chunk) {
return $value === $chunk->last();
});
// [['A', 'A'], ['B', 'B'], ['C', 'C', 'C'], ['D']]
Reducing and Aggregating
reduce()
Reduce the collection to a single value:
$total = collect([1, 2, 3])->reduce(function ($carry, $item) {
return $carry + $item;
}, 0); // 6
reduceSpread()
Like reduce() but spreads the carry value:
$result = collect([1, 2, 3, 4])->reduceSpread(function ($carry, $count, $product, $item) {
return [
$carry + 1,
$count + $item,
$product * $item,
];
}, [0, 0, 1]);
// [4, 10, 24]
Collection Pipelines and Method Chaining
One of the most powerful aspects of Collections is the ability to chain methods together into a "pipeline" of operations. This creates a declarative, readable flow of data transformations:
$result = User::all()
->filter(function ($user) {
return $user->active;
})
->map(function ($user) {
return [
'name' => $user->name,
'purchases' => $user->purchases->count(),
];
})
->sortByDesc('purchases')
->take(10)
->keyBy('name');
This code clearly expresses its intent: "Get all users, keep only active ones, transform them to name/purchase count pairs, sort by purchase count descending, take the top 10, and key them by name."
Creating Custom Collection Pipelines
For complex operations that you use frequently, you can create custom collection pipelines:
Collection::macro('topSpenders', function ($count = 10) {
return $this
->filter->active
->map(function ($user) {
return [
'name' => $user->name,
'total_spent' => $user->orders->sum('amount'),
];
})
->sortByDesc('total_spent')
->take($count);
});
// Usage
$topSpenders = User::all()->topSpenders(5);
Higher-Order Messages: Shorthand Syntax
Laravel 5.4 introduced higher-order messages, a shorthand syntax for common collection operations:
// Instead of
$users->filter(function ($user) {
return $user->active;
});
// You can use
$users->filter->active;
// Works with methods too
$users->map->getFullName();
// And you can chain them
$users->filter->active->map->name;
This syntax works for:
mapfilterrejecteachsomeeveryfirstpartition
LazyCollection: For Working with Large Datasets
For very large datasets, standard Collections can consume too much memory. Laravel provides LazyCollection which uses PHP generators to load only one item at a time:
use Illuminate\Support\LazyCollection;
// Process a large file without loading it all into memory
LazyCollection::make(function () {
$handle = fopen('large-file.csv', 'r');
while (($line = fgetcsv($handle)) !== false) {
yield $line;
}
fclose($handle);
})
->map(function ($row) {
return [
'name' => $row[0],
'email' => $row[1],
];
})
->filter(function ($row) {
return filter_var($row['email'], FILTER_VALIDATE_EMAIL);
})
->each(function ($row) {
// Process each row
});
When to Use LazyCollection
LazyCollection is ideal for:
- Processing large files
- Working with large database results
- Operations on large datasets where you don't need all results at once
Note that not all collection methods work with lazy evaluation. Methods that need to see all items (like sort or reverse) will trigger full evaluation.
Custom Collections
Creating a Custom Collection Class
For domain-specific collection behavior, you can create custom collection classes:
namespace App\Collections;
use Illuminate\Support\Collection;
class UserCollection extends Collection
{
public function activeUsers()
{
return $this->filter->active;
}
public function formatForReport()
{
return $this->map(function ($user) {
return [
'name' => $user->name,
'email' => $user->email,
'joined' => $user->created_at->format('Y-m-d'),
];
});
}
}
Using Custom Collections with Eloquent
You can tell Eloquent models to use your custom collection:
namespace App\Models;
use App\Collections\UserCollection;
use Illuminate\Database\Eloquent\Model;
class User extends Model
{
public function newCollection(array $models = [])
{
return new UserCollection($models);
}
}
Now, User::all() will return your custom collection with its special methods.
Performance Considerations
Collections are convenient but come with overhead. Here are some performance considerations:
Collection vs. Array Performance
Collections add a small overhead compared to raw PHP arrays. For small datasets, this is negligible. For very large datasets or performance-critical code, consider:
- Using arrays directly for extremely performance-sensitive code
- Using LazyCollection for large datasets
- Profiling your actual use case (premature optimization is the root of all evil)
Common Performance Pitfalls
Creating Unnecessary Intermediate Collections
Each collection method that returns a new collection creates a new object:
// Creates multiple intermediate collections
$result = $collection->map(...)->filter(...)->values();
For very large collections, this can add up. Consider using reduce() for complex transformations that would otherwise create many intermediate collections.
Inefficient Method Chains
Some method combinations can be inefficient:
// Less efficient: maps everything, then filters
$collection->map(...)->filter(...);
// More efficient: filters first, maps fewer items
$collection->filter(...)->map(...);
Think about the order of operations to minimize work.
Eager Loading with Eloquent Collections
When working with Eloquent Collections, eager loading relationships can dramatically improve performance:
// Causes N+1 query problem
User::all()->map(function ($user) {
return $user->posts->count();
});
// Much more efficient
User::with('posts')->get()->map(function ($user) {
return $user->posts->count();
});
Real-World Collection Recipes
Here are some practical examples of using collections to solve common problems:
Building a Menu Structure
$menuItems = MenuItem::all();
$menu = $menuItems
->where('parent_id', null)
->map(function ($item) use ($menuItems) {
$item->children = $menuItems
->where('parent_id', $item->id)
->values();
return $item;
});
Transforming CSV Data
$csv = collect(file('data.csv'))
->map(fn($line) => str_getcsv($line))
->skip(1) // Skip header row
->map(function ($row) {
return [
'name' => $row[0],
'email' => $row[1],
'phone' => $row[2],
];
});
Generating Reports
$salesReport = Order::with('items', 'customer')
->get()
->groupBy(function ($order) {
return $order->created_at->format('Y-m');
})
->map(function ($monthOrders) {
return [
'total_orders' => $monthOrders->count(),
'total_revenue' => $monthOrders->sum('total'),
'average_order_value' => $monthOrders->avg('total'),
'top_products' => $monthOrders
->flatMap->items
->countBy('product_id')
->sort()
->reverse()
->take(5),
];
});
Building an Activity Feed
$activities = collect([
...user->activities,
...user->posts,
...user->comments,
])
->sortByDesc('created_at')
->take(20)
->map(function ($item) {
return [
'type' => get_class($item),
'date' => $item->created_at,
'data' => $item->toArray(),
];
});
Testing Collection Code
Collections are easy to test due to their immutability and fluent interface:
public function test_it_filters_and_transforms_users()
{
$users = collect([
['name' => 'John', 'active' => true, 'role' => 'admin'],
['name' => 'Jane', 'active' => true, 'role' => 'user'],
['name' => 'Dave', 'active' => false, 'role' => 'user'],
]);
$result = $users
->filter(fn($user) => $user['active'])
->map(fn($user) => [
'name' => $user['name'],
'is_admin' => $user['role'] === 'admin',
]);
$this->assertEquals([
['name' => 'John', 'is_admin' => true],
['name' => 'Jane', 'is_admin' => false],
], $result->values()->all());
}
Extending Collections with Macros
You can add your own methods to the Collection class using macros:
// In a service provider
Collection::macro('toUpper', function () {
return $this->map(function ($value) {
return is_string($value) ? strtoupper($value) : $value;
});
});
// Usage
collect(['a', 'b', 'c'])->toUpper(); // ['A', 'B', 'C']
Creating a Collection Macros Package
For reusable collection extensions, consider creating a package:
namespace App\Providers;
use Illuminate\Support\Collection;
use Illuminate\Support\ServiceProvider;
class CollectionMacroServiceProvider extends ServiceProvider
{
public function boot()
{
Collection::macro('toOptions', function ($valueField = 'id', $textField = 'name') {
return $this->map(function ($item) use ($valueField, $textField) {
return [
'value' => data_get($item, $valueField),
'text' => data_get($item, $textField),
];
});
});
Collection::macro('transpose', function () {
$items = array_map(function (...$items) {
return $items;
}, ...$this->values());
return new static($items);
});
}
}
Collections and Functional Programming
Laravel Collections implement many functional programming concepts:
Immutability
Most collection methods return a new collection rather than modifying the original:
$original = collect([1, 2, 3]);
$doubled = $original->map(fn($n) => $n * 2);
// $original still contains [1, 2, 3]
// $doubled contains [2, 4, 6]
Function Composition
Method chaining is a form of function composition:
$result = $collection
->map(fn($x) => $x * 2)
->filter(fn($x) => $x > 5)
->values();
Higher-Order Functions
Many collection methods take functions as arguments:
$collection->map(function ($x) { return $x * 2; });
$collection->filter(function ($x) { return $x > 5; });
$collection->reduce(function ($carry, $x) { return $carry + $x; });
Conclusion
Laravel Collections transform the way you work with arrays and data sets in PHP. By providing a fluent, expressive API that encourages method chaining and declarative programming, they help you write code that is more readable, maintainable, and less prone to bugs.
Further Reading:
While we've covered many advanced techniques in this article, the best way to master Collections is to use them in your everyday coding. Look for opportunities to refactor procedural array operations into collection pipelines. Create custom macros for operations you use frequently. And don't be afraid to create domain-specific collection classes that encapsulate the behavior specific to your application.
As you become more comfortable with the collection API, you'll find yourself writing less code that accomplishes more, with fewer bugs and greater readability. That's the true power of Laravel Collections – they help you write better code faster.
Add Comment
No comments yet. Be the first to comment!