A set of useful Laravel collection macros
This repository contains some useful collection macros.
Spatie is a webdesign agency based in Antwerp, Belgium. You'll find an overview of all our open source projects on our website.
Postcardware
You're free to use this package (it's MIT-licensed), but if it makes it to your production environment you are required to send us a postcard from your hometown, mentioning which of our package(s) you are using.
Our address is: Spatie, Samberstraat 69D, 2060 Antwerp, Belgium.
The best postcards will get published on the open source page on our website.
Installation
You can pull in the package via composer:
composer require spatie/laravel-collection-macros
This service provider must be installed.
// config/app.php
'providers' => [
...
Spatie\CollectionMacros\CollectionMacroServiceProvider::class,
];
Usage
These macro's will be added to the Illuminate\Support\Collection
class.
dd
Dumps the contents of the collection and terminates the script. This macro makes debugging a collection much easier.
collect([1,2,3])->dd();
dump
Dumps the given arguments together with the current collection. This macro makes debugging a chain of collection functions much easier.
collect([1,2,3])
->dump('original')
->map(function(int $number) {
return $number * 2;
})
->dump('modified')
->dd();
groupByModel
Similar to groupBy
, but groups the collection by an Eloquent model. Since the key is an object instead of an integer or string, the results are divided into separate arrays.
$collection = collect([
['model' => $model1, 'foo' => 'bar'],
['model' => $model1, 'foo' => 'baz'],
['model' => $model2, 'foo' => 'qux'],
]);
$collection->groupByModel('model');
// [
// [
// 'model' => $model1,
// 'items' => [
// ['model' => $model1, 'foo' => 'bar'],
// ['model' => $model1, 'foo' => 'baz'],
// ],
// ],
// [
// 'model' => $model2,
// 'items' => [
// ['model' => $model2, 'foo' => 'qux'],
// ],
// ],
// ];
You can also use a callable for more flexibility:
$collection->groupByModel(function ($item) {
return $item['model']
});
If you want to specify the model key's name, you can pass it as the second parameter:
$collection->groupByModel('model', 'myModel');
// [
// [
// 'myModel' => $model1,
// 'items' => [
// ['model' => $model1, 'foo' => 'bar'],
// ['model' => $model1, 'foo' => 'baz'],
// ],
// ],
// [
// 'myModel' => $model2,
// 'items' => [
// ['model' => $model2, 'foo' => 'qux'],
// ],
// ],
// ];
ifAny
Executes the passed callable if the collection isn't empty. The entire collection will be returned.
collect()->ifAny(function(Collection $collection) { // empty collection so this won't get called
echo 'Hello';
});
collect([1, 2, 3])->ifAny(function(Collection $collection) { // non-empty collection so this will get called
echo 'Hello';
});
ifEmpty
Executes the passed callable if the collection is empty. The entire collection will be returned.
collect()->ifEmpty(function(Collection $collection) { // empty collection so this will called
echo 'Hello';
});
collect([1, 2, 3])->ifEmpty(function(Collection $collection) { // non-empty collection so this won't get called
echo 'Hello';
});
none
Checks whether a collection doesn't contain any occurrences of a given item, key-value pair, or passing truth test. The function accepts the same parameters as the contains
collection method.
collect(['foo'])->none('bar'); // returns true
collect(['foo'])->none('foo'); // returns false
collect([['name' => 'foo']])->none('name', 'bar'); // returns true
collect([['name' => 'foo']])->none('name', 'foo'); // returns false
collect(['name' => 'foo'])->none(function ($key, $value) {
return $key === 'name' && $value === 'bar';
}); // returns true
Note: When using a callable as argument, ``Collection::none
be
haves differently in Laravel 5.3 and higher. In 5.2, the parameter order is `$key, $value`, and in 5.3+ the parameter order is `$value, $key`.
range
Creates a new collection instance with a range of numbers. This functions accepts the same parameters as PHP's standard range
function.
collect()->range(1, 3)->toArray(); //returns [1,2,3]
split
Splits a collection into the given number of groups.
$collection = collect(['a', 'b', 'c', 'd', 'e', 'f'])->split(3);
$collection->count(); // returns 3
$collection->first(); // returns a collection with 'a' and 'b';
$collection->last(); // returns a collection with 'e' and 'f';
validate
Returns true
if the given $callback
returns true for every item. If $callback
is a string or an array, regard it as a validation rule.
collect(['foo', 'foo'])->validate(function ($item) {
return $item === 'foo';
}); // returns true
collect(['sebastian@spatie.be', 'bla'])->validate('email'); // returns false
collect(['sebastian@spatie.be', 'freek@spatie.be'])->validate('email'); // returns true
toAssoc
Transform a collection into an associative array form collection item.
$collection = collect(['a', 'b'], ['c', 'd'], ['e', 'f'])->toAssoc();
$collection->toArray(); // returns ['a' => 'b', 'c' => 'd', 'e' => 'f']
mapToAssoc
Transform a collection into an associative array form collection item, allowing you to pass a callback to customize its key and value through a map operation.
$employees = collect([
[
'name' => 'John',
'department' => 'Sales',
'email' => 'john@example.com',
],
[
'name' => 'Jane',
'department' => 'Marketing',
'email' => 'jane@example.com',
],
]);
$employees->mapToAssoc(function ($employee) {
return [$employee['email'], $employee['name']];
});
$employees->toArray(); // returns ['john@example.com' => 'John', 'jane@example.com' => 'Jane']
partition
Outputs a collection with two elements. Items in the first element did pass the given $callback
, items in the second element did not.
collect(range(1,10))->partition(function($i) {
return $i <= 5;
})->toArray();
// [
// collect([1, 2, 3, 4, 5]),
// collect([6, 7, 8, 9, 10]),
// ]
transpose
The goal of transpose is to rotate a multidimensional array, turning the rows into columns and the columns into rows.
collect([
['Jane', 'Bob', 'Mary'],
['jane@example.com', 'bob@example.com', 'mary@example.com'],
['Doctor', 'Plumber', 'Dentist'],
])->transpose()->toArray();
// [
// ['Jane', 'jane@example.com', 'Doctor'],
// ['Bob', 'bob@example.com', 'Plumber'],
// ['Mary', 'mary@example.com', 'Dentist'],
// ]
Changelog
Please see CHANGELOG for more information what has changed recently.
Testing
$ composer test
Contributing
Please see CONTRIBUTING for details.
Security
If you discover any security related issues, please email freek@spatie.be instead of using the issue tracker.
Credits
About Spatie
Spatie is a webdesign agency based in Antwerp, Belgium. You'll find an overview of all our open source projects on our website.
License
The MIT License (MIT). Please see License File for more information.