A set of useful Laravel collection macros
This repository contains some useful collection macros.
This version is targeted at Laravel 5.4. For Laravel 5.2 or 5.3, take a look at the v1 branch.
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();
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
behaves 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]
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(['[email protected]', 'bla'])->validate('email'); // returns false
collect(['[email protected]', '[email protected]'])->validate('email'); // returns true
fromPairs
Transform a collection into an associative array form collection item.
$collection = collect(['a', 'b'], ['c', 'd'], ['e', 'f'])->fromPairs();
$collection->toArray(); // returns ['a' => 'b', 'c' => 'd', 'e' => 'f']
toPairs
Transform a collection in to a array with pairs.
$collection = collect(['a' => 'b', 'c' => 'd', 'e' => 'f'])->toPairs();
$collection->toArray(); // returns ['a', 'b'], ['c', 'd'], ['e', 'f']
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'],
['[email protected]', '[email protected]', '[email protected]'],
['Doctor', 'Plumber', 'Dentist'],
])->transpose()->toArray();
// [
// ['Jane', '[email protected]', 'Doctor'],
// ['Bob', '[email protected]', 'Plumber'],
// ['Mary', '[email protected]', 'Dentist'],
// ]
withSize
Create a new collection with the specified amount of items.
Collection::withSize(1)->toArray(); // return [1];
Collection::withSize(5)->toArray(); // return [1,2,3,4,5];
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'],
// ],
// ],
// ];
after
Get the next item from the collection.
$collection = collect([1,2,3]);
$currentItem = 2;
$currentItem = $collection->after($currentItem); // return 3;
$collection->after($currentItem); // return null;
$currentItem = $collection->after(function($item) {
return $item > 1;
}); // return 3;
You can also pass a second parameter to be used as a fallback.
$collection = collect([1,2,3]);
$currentItem = 3;
$collection->after($currentItem, $collection->first()); // return 1;
before
Get the previous item from the collection.
$collection = collect([1,2,3]);
$currentItem = 2;
$currentItem = $collection->before($currentItem); // return 1;
$collection->before($currentItem); // return null;
$currentItem = $collection->before(function($item) {
return $item > 2;
}); // return 2;
You can also pass a second parameter to be used as a fallback.
$collection = collect([1,2,3]);
$currentItem = 1;
$collection->before($currentItem, $collection->last()); // return 3;
collect
Get an item at a given key, and collect it.
$collection = collect([
'foo' => [1, 2, 3],
'bar' => [4, 5, 6],
]);
$collection->collect('foo'); // Collection([1, 2, 3])
You can also pass a second parameter to be used as a fallback.
$collection = collect([
'foo' => [1, 2, 3],
'bar' => [4, 5, 6],
]);
$collection->collect('baz', ['Nope']); // Collection(['Nope'])
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 [email protected] 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.