Package Data | |
---|---|
Maintainer Username: | spatie |
Maintainer Contact: | freek@spatie.be (Freek Van der Herten) |
Package Create Date: | 2016-07-26 |
Package Last Update: | 2024-12-11 |
Home Page: | https://freek.dev/540-some-handy-collection-macros |
Language: | PHP |
License: | MIT |
Last Refreshed: | 2024-12-22 03:01:41 |
Package Statistics | |
---|---|
Total Downloads: | 3,571,689 |
Monthly Downloads: | 116,584 |
Daily Downloads: | 1,403 |
Total Stars: | 1,765 |
Total Watchers: | 29 |
Total Forks: | 142 |
Total Open Issues: | 0 |
This repository contains some useful collection macros.
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-macros
The package will automatically register itself.
after
at
before
chunkBy
collect
eachCons
extract
filterMap
firstOrFail
fromPairs
glob
groupByModel
head
ifAny
ifEmpty
join
none
paginate
parallelMap
pluckToArray
prioritize
rotate
sectionBy
simplePaginate
sliceBefore
tail
toPairs
transpose
validate
withSize
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;
at
Retrieve an item at an index.
$data = new Collection([1, 2, 3]);
$data->at(0); // 1
$data->at(1); // 2
$data->at(-1); // 3
second
Retrieve item at the second index.
$data = new Collection([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
$data->second(); // 2
third
Retrieve item at the third index.
$data = new Collection([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
$data->third(); // 3
fourth
Retrieve item at the fourth index.
$data = new Collection([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
$data->fourth(); // 4
fifth
Retrieve item at the fifth index.
$data = new Collection([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
$data->fifth(); // 5
sixth
Retrieve item at the sixth index.
$data = new Collection([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
$data->sixth(); // 6
seventh
Retrieve item at the seventh index.
$data = new Collection([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
$data->seventh(); // 7
eighth
Retrieve item at the eighth index.
$data = new Collection([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
$data->eighth(); // 8
ninth
Retrieve item at the ninth index.
$data = new Collection([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
$data->ninth(); // 9
tenth
Retrieve item at the tenth index.
$data = new Collection([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
$data->tenth(); // 10
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;
chunkBy
Chunks the values from a collection into groups as long the given callback is true. If the optional parameter $preserveKeys
as true
is passed, it will preserve the original keys.
collect(['A', 'A', 'B', 'A'])->chunkBy(function($item) {
return $item == 'A';
}); // return Collection([['A', 'A'],['B'], ['A']])
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'])
eachCons
Get the following consecutive neighbours in a collection from a given chunk size. If the optional parameter $preserveKeys
as true
is passed, it will preserve the original keys.
collect([1, 2, 3, 4])->eachCons(2); // return collect([[1, 2], [2, 3], [3, 4]])
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 arraynull
instead of omitting itextract
is useful when using PHP 7.1 short list()
syntax.
[$name, $role] = collect($user)->extract('name', 'role.name');
filterMap
Map a collection and remove falsy values in one go.
$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]
firstOrFail
Get the first item. Throws Spatie\CollectionMacros\Exceptions\CollectionItemNotFound
if the item was not found.
$collection = collect([1, 2, 3, 4, 5, 6])->firstOrFail();
$collection->toArray(); // returns [1]
collect([])->firstOrFail(); // throws Spatie\CollectionMacros\Exceptions\CollectionItemNotFound
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']
glob
Returns a collection of a glob()
result.
Collection::glob('config/*.php');
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.
$posts->groupByModel('category');
// [
// [$categoryA, [/*...$posts*/]],
// [$categoryB, [/*...$posts*/]],
// ];
Full signature: groupByModel($callback, $preserveKeys, $modelKey, $itemsKey)
head
Retrieves first item from the collection.
$collection = collect([1,2,3]);
$collection->head(); // return 1
$collection = collect([]);
$collection->head(); // return null
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
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 = [])
parallelMap
Identical to map
but each item in the collection will be processed in parallel. Before using this macro you should pull in the amphp/parallel-functions
package.
composer require amphp/parallel-functions
Be aware that under the hood some overhead is introduced to make the parallel processing possible. When your $callable
is only a simple operation it's probably better to use map
instead. Also keep in mind that parallelMap
can be memory intensive.
$pageSources = collect($urls)->parallelMap(function($url) {
return file_get_contents($url);
});
The page contents of the given $urls
will be fetched at the same time. The underlying amp
sets a maximum of 32
concurrent processes by default.
There is a second (optional) parameter, through which you can define a custom parallel processing pool. It looks like this:
use Amp\Parallel\Worker\DefaultPool;
$pool = new DefaultPool(8);
$pageSources = collect($urls)->parallelMap(function($url) {
return file_get_contents($url);
}, $pool);
If you don't need to extend the worker pool, or can't be bothered creating the new pool yourself; you can use an integer the the number of workers you'd like to use. A new DefaultPool
will be created for you:
$pageSources = collect($urls)->parallelMap(function($url) {
return file_get_contents($url);
}, 8);
This helps to reduce the memory overhead, as the default worker pool limit is 32
(as defined in amphp/parallel
). Using fewer worker threads can significantly reduce memory and processing overhead, in many cases. Benchmark and customise the worker thread limit to suit your particular use-case.
pluckToArray
Returns array of values of a given key.
$collection = collect([
['a' => 1, 'b' => 10],
['a' => 2, 'b' => 20],
['a' => 3, 'b' => 30]
]);
$collection->pluckToArray('a'); // returns [1, 2, 3]
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]
rotate
Rotate the items in the collection with given offset
$collection = collect([1, 2, 3, 4, 5, 6]);
$rotate = $collection->rotate(1);
$rotate->toArray();
// [2, 3, 4, 5, 6, 1]
sectionBy
Splits a collection into sections grouped by a given key. Similar to groupBy
but respects the order of the items in the collection and reuses existing keys.
$collection = collect([
['name' => 'Lesson 1', 'module' => 'Basics'],
['name' => 'Lesson 2', 'module' => 'Basics'],
['name' => 'Lesson 3', 'module' => 'Advanced'],
['name' => 'Lesson 4', 'module' => 'Advanced'],
['name' => 'Lesson 5', 'module' => 'Basics'],
]);
$collection->sectionBy('module');
// [
// ['Basics', [
// ['name' => 'Lesson 1', 'module' => 'Basics'],
// ['name' => 'Lesson 2', 'module' => 'Basics'],
// ]],
// ['Advanced', [
// ['name' => 'Lesson 3', 'module' => 'Advanced'],
// ['name' => 'Lesson 4', 'module' => 'Advanced'],
// ]],
// ['Basics', [
// ['name' => 'Lesson 5', 'module' => 'Basics'],
// ]],
// ];
Full signature: sectionBy($callback, $preserveKeys, $sectionKey, $itemsKey)
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.
sliceBefore
Slice the values out from a collection before the given callback is true. If the optional parameter $preserveKeys
as true
is passed, it will preserve the original keys.
collect([20, 51, 10, 50, 66])->sliceBefore(function($item) {
return $item > 50;
}); // return collect([[20],[51, 10, 50], [66])
tail
Extract the tail from a collection. So everything except the first element. It's a shorthand for slice(1)->values()
, but nevertheless very handy. If the optional parameter $preserveKeys
as true
is passed, it will preserve the keys and fallback to slice(1)
.
collect([1, 2, 3])->tail(); // return collect([2, 3])
toPairs
Transform a collection into an 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'],
// ]
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
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];
Please see CHANGELOG for more information what has changed recently.
$ composer test
Please see CONTRIBUTING for details.
If you discover any security related issues, please email freek@spatie.be 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.