spatie/laravel-collection-macros

To use these collection macros in your Laravel project, install the package using Composer. The package will automatically register its macros within the Laravel framework.

composer require spatie/laravel-collection-macros

The extract() macro is similar to only(), but it returns a flat array of values instead of an associative array. If a requested key does not exist, it fills the position with null. This is specifically designed for use with PHP's list() or short array destructuring syntax.

[$name, $role] = collect($user)->extract('name', 'role.name');

The groupByModel() macro is a specialized version of groupBy(). Instead of using strings or integers as keys, it groups the collection by an Eloquent model instance, resulting in an array where the keys are the model objects themselves.

Signature: groupByModel($callback, $preserveKeys, $modelKey, $itemsKey)

$posts->groupByModel('category');

// Result structure:
// [
//     [$categoryA, [/*...$posts*/]],
//     [$categoryB, [/*...$posts*/]],
// ]

The collectBy() macro retrieves an item at a specific key and returns it as a new collection. It accepts an optional fallback value.

$collection = collect([
    'foo' => [1, 2, 3],
    'bar' => [4, 5, 6],
]);

$collection->collectBy('foo'); // Collection([1, 2, 3])
$collection->collectBy('baz', ['Nope']); // Collection(['Nope'])

The filterMap() macro allows you to transform items and remove falsy results in a single operation, avoiding the need to chain map() and filter().

$collection = collect([1, 2, 3, 4, 5, 6])->filterMap(function ($number) {
    $quotient = $number / 3;
    return is_integer($quotient) ? $quotient : null;
});

$collection->toArray(); // [1, 2]

$collection = collect([1, 2, 3, 4, 5, 6])->filterMap(function ($number) {
    $quotient = $number / 3;

    return is_integer($quotient) ? $quotient : null;
});

$collection->toArray(); // returns [1, 2]

The before() macro retrieves the item preceding a given item or condition. You can pass a value or a callback. An optional second parameter provides a fallback if no previous item exists.

$collection = collect([1,2,3]);

// Using a value
$collection->before(2); // returns 1
$collection->before(1); // returns null

// Using a callback
$collection->before(function($item) {
    return $item > 2;
}); // returns 2

// Using a fallback
$collection->before(1, $collection->last()); // returns 3

$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;

The firstOrPush() macro attempts to find the first item that matches a given callback. If no match is found, it pushes a fallback value into the collection. You can optionally specify a target collection as the third parameter.

// Push to the current collection
$collection = collect([1, 2, 3])->firstOrPush(fn($item) => $item === 4, 4);
$collection->toArray(); // [1, 2, 3, 4]

// Push to a specific target collection
$target = collect([1, 2, 3]);
$collection->filter()->firstOrPush(fn($item) => $item === 4, 4, $target);

$collection = collect([1, 2, 3])->firstOrPush(fn($item) => $item === 4, 4);

$collection->toArray(); // returns [1, 2, 3, 4]

Use these macros to check for the presence of multiple values:

• containsAny(array $values): Returns true if one or more of the given values exist in the collection.
• containsAll(array $values): Returns true if all given values exist in the collection.

$collection = collect(['a', 'b', 'c']);

$collection->containsAny(['b', 'c', 'd']); // true
$collection->containsAll(['b', 'c']); // true
$collection->containsAll(['c', 'd']); // false

$collection = collect(['a', 'b', 'c']);

$collection->containsAny(['b', 'c', 'd']); // returns true
$collection->containsAll(['b', 'c',]); // returns true

The weightedRandom() macro returns a random item from the collection based on a weight. You can specify the weight by passing a string (the field name) or a callback.

// Using a field name
$randomItem = collect([
    ['value' => 'a', 'weight' => 30],
    ['value' => 'b', 'weight' => 20],
    ['value' => 'c', 'weight' => 10],
])->weightedRandom('weight');

// Using a callback
$randomItem = collect([
    ['value' => 'a', 'weight' => 30],
    ['value' => 'b', 'weight' => 20],
    ['value' => 'c', 'weight' => 10],
])->weightedRandom(function(array $item) {
   return $item['weight'];
});

You can retrieve items at specific indices using the at() method, which supports negative indices for counting from the end. Additionally, there are semantic macros for common positions:

• at(int $index): Retrieve item at a specific index.
• second(): Retrieve item at index 1.
• third(): Retrieve item at index 2.
• fourth(): Retrieve item at index 3.
• fifth(): Retrieve item at index 4.
• sixth(): Retrieve item at index 5.
• seventh(): Retrieve item at index 6.
• eighth(): Retrieve item at index 7.
• ninth(): Retrieve item at index 8.
• tenth(): Retrieve item at index 9.
• getNth(int $n): Retrieve the nth item.

$data = new Collection([1, 2, 3]);

$data->at(0); // 1
$data->at(-1); // 3
$data->second(); // 2
$data->getNth(3); // 3

$data = new Collection([1, 2, 3]);

$data->at(0); // 1
$data->at(1); // 2
$data->at(-1); // 3