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.
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.
You can pull in the package via composer:
composer require spatie/laravel-collection-macrosThis service provider must be installed.
// config/app.php
'providers' => [
...
Spatie\CollectionMacros\CollectionMacroServiceProvider::class,
];These macro's will be added to the Illuminate\Support\Collection class.
Dumps the contents of the collection and terminates the script. This macro makes debugging a collection much easier.
collect([1,2,3])->dd();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();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';
});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';
});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 trueNote: When using a callable as argument,
Collection::nonebehaves 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.
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]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 trueTransform 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']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']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'],
// ]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];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'],
// ],
// ],
// ];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;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;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'])Please see CHANGELOG for more information what has changed recently.
$ composer testPlease see CONTRIBUTING for details.
If you discover any security related issues, please email [email protected] instead of using the issue tracker.
Spatie is a webdesign agency based in Antwerp, Belgium. You'll find an overview of all our open source projects on our website.
The MIT License (MIT). Please see License File for more information.