README

This package is a fork of spatie/laravel-collection-macros. It contains a subset of the original macros as well as a few extra ones.

This package is intended for PERSONAL USE. Please see the original Spatie package if you would like to submit a PR or request a feature.

Installation

Install the package via composer:

composer require code-distortion/laravel-collection-macros

The package will automatically register itself.

Macros

Macros kept from the original spatie package:

• catch
• extract
• glob
• ifAny
• ifEmpty
• none
• paginate
• prioritize
• simplePaginate
• try
• transpose
• validate

New macros added:

• keepValues
• keyedKeys
• rejectValues

catch

See Try

extract

Extract keys from a collection. This is very similar to only, with two key differences:

• extract returns an array of values, not an associative array
• If a value doesn't exist, it will fill the value with null instead of omitting it

extract is useful when using PHP 7.1 short list() syntax.

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

glob

Returns a collection of a glob() result.

Collection::glob('config/*.php');

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';
});

keepValues

Returns a collection containing only values that were in the given list.

collect(['foo', 'bar'])->keepValues(['foo'])->toArray(); // ['foo']

keepValues accepts a second parameter to turn strict-comparisons on (default false).

collect(['123', 456])->keepValues(['123', '456'], true)->toArray(); // ['123']

keyedKeys

Returns a collection where the values are the same as the keys.

collect(['foo' => 1, 'bar' => 2])->keyedKeys()->toArray(); // ['foo' => 'foo', 'bar' => 'bar']

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

paginate

Create a LengthAwarePaginator instance for the items in the collection.

collect($posts)->paginate(5);

This paginates the contents of $posts with 5 items per page. paginate accepts quite some options, head over to the Laravel docs for an in-depth guide.

paginate(int $perPage = 15, string $pageName = 'page', int $page = null, int $total = null, array $options = [])

prioritize

Move elements to the start of the collection.

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

$collection
   ->prioritize(function(array $item) {
      return $item['id'] === 2;
   })
   ->pluck('id')
   ->toArray(); // returns [2, 1, 3]

rejectValues

Removes the given values from the collection.

collect(['foo', 'bar'])->rejectValues(['foo'])->toArray(); // ['bar']

rejectValues accepts a second parameter to turn strict-comparisons on (default false).

collect(['123', 456])->rejectValues(['123', '456'], true)->toArray(); // [456]

simplePaginate

Create a Paginator instance for the items in the collection.

collect($posts)->simplePaginate(5);

This paginates the contents of $posts with 5 items per page. simplePaginate accepts quite some options, head over to the Laravel docs for an in-depth guide.

simplePaginate(int $perPage = 15, string $pageName = 'page', int $page = null, int $total = null, array $options = [])

For a in-depth guide on pagination, check out the Laravel docs.

try

If any of the methods between try and catch throw an exception, then the exception can be handled in catch.

collect(['a', 'b', 'c', 1, 2, 3])
    ->try()
    ->map(fn ($letter) => strtoupper($letter))
    ->each(function() {
        throw new Exception('Explosions in the sky');
    })
    ->catch(function (Exception $exception) {
        // handle exception here
    })
    ->map(function() {
        // further operations can be done, if the exception wasn't rethrow in the `catch`
    });

While the methods are named try/catch for familiarity with PHP, the collection itself behaves more like a database transaction. So when an exception is thrown, the original collection (before the try) is returned.

You may gain access to the collection within catch by adding a second parameter to your handler. You may also manipulate the collection within catch by returning a value.

$collection = collect(['a', 'b', 'c', 1, 2, 3])
    ->try()
    ->map(function ($item) {
        throw new Exception();
    })
    ->catch(function (Exception $exception, $collection) {
        return collect(['d', 'e', 'f']);
    })
    ->map(function ($item) {
        return strtoupper($item);
    });

// ['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'],
// ]

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

Changelog

Please see CHANGELOG for more information what has changed recently.

Testing

$ composer test

Contributing

Contributions are not being sought for this package. Please see the original spatie/laravel-collection-macros package if you would like to contribute.

Security

If you discover any security related issues, please email tim@code-distortion.net instead of using the issue tracker.

Credits

• Freek Van der Herten
• Sebastian De Deyne
• Tim Chandler (fork)
• All Contributors

License

The MIT License (MIT). Please see License File for more information.