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(['sebastian@spatie.be', 'bla'])->validate('email'); // returns false
collect(['sebastian@spatie.be', 'freek@spatie.be'])->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'],
    ['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'],
// ]

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 freek@spatie.be instead of using the issue tracker.

Credits

• Freek Van der Herten
• Sebastian De Deyne
• All Contributors

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.