Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/myxiaoao/hyperf-collection-macros
A set of useful Hyperf collection macros.
https://github.com/myxiaoao/hyperf-collection-macros
collection hyperf
Last synced: 2 days ago
JSON representation
A set of useful Hyperf collection macros.
- Host: GitHub
- URL: https://github.com/myxiaoao/hyperf-collection-macros
- Owner: myxiaoao
- License: mit
- Created: 2022-08-04T12:05:19.000Z (over 2 years ago)
- Default Branch: master
- Last Pushed: 2022-08-11T06:57:30.000Z (over 2 years ago)
- Last Synced: 2024-04-19T21:15:00.821Z (7 months ago)
- Topics: collection, hyperf
- Language: PHP
- Homepage:
- Size: 69.3 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# A set of useful Hyperf collection macros
This repository contains some useful collection macros.
## Installation
You can pull in the package via composer:
``` bash
composer require cooper/hyperf-collection-macros
```
The package will automatically register itself.
## Macros
- [`after`](#after)
- [`at`](#at)
- [`second`](#second)
- [`third`](#third)
- [`fourth`](#fourth)
- [`fifth`](#fifth)
- [`sixth`](#sixth)
- [`seventh`](#seventh)
- [`eighth`](#eighth)
- [`ninth`](#ninth)
- [`tenth`](#tenth)
- [`getNth`](#getNth)
- [`before`](#before)
- [`catch`](#catch)
- [`chunkBy`](#chunkby)
- [`collectBy`](#collectBy)
- [`containsAny`](#containsAny)
- [`containsAll`](#containsAll)
- [`eachCons`](#eachcons)
- [`extract`](#extract)
- [`filterMap`](#filtermap)
- [`firstOrFail`](#firstorfail)
- [`firstOrPush`](#firstorpush)
- [`fromPairs`](#frompairs)
- [`glob`](#glob)
- [`groupByModel`](#groupbymodel)
- [`head`](#head)
- [`if`](#if)
- [`ifAny`](#ifany)
- [`ifEmpty`](#ifempty)
- [`insertAfter`](#insertafter)
- [`insertAfterKey`](#insertafterkey)
- [`insertAt`](#insertat)
- [`insertBefore`](#insertbefore)
- [`insertBeforeKey`](#insertbeforekey)
- [`none`](#none)
- [`path`](#path)
- [`pluckMany`](#pluckmany)
- [`pluckToArray`](#plucktoarray)
- [`prioritize`](#prioritize)
- [`recursive`](#recursive)
- [`rotate`](#rotate)
- [`sectionBy`](#sectionby)
- [`sliceBefore`](#slicebefore)
- [`tail`](#tail)
- [`toPairs`](#topairs)
- [`transpose`](#transpose)
- [`weightedRandom`](#weightedRandom)
- [`withSize`](#withsize)
### `after`
Get the next item from the collection.
```php
$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.
```php
$collection = collect([1,2,3]);
$currentItem = 3;
$collection->after($currentItem, $collection->first()); // return 1;
```
### `at`
Retrieve an item at an index.
```php
$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.
```php
$data = new Collection([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
$data->second(); // 2
```
### `third`
Retrieve item at the third index.
```php
$data = new Collection([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
$data->third(); // 3
```
### `fourth`
Retrieve item at the fourth index.
```php
$data = new Collection([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
$data->fourth(); // 4
```
### `fifth`
Retrieve item at the fifth index.
```php
$data = new Collection([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
$data->fifth(); // 5
```
### `sixth`
Retrieve item at the sixth index.
```php
$data = new Collection([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
$data->sixth(); // 6
```
### `seventh`
Retrieve item at the seventh index.
```php
$data = new Collection([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
$data->seventh(); // 7
```
### `eighth`
Retrieve item at the eighth index.
```php
$data = new Collection([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
$data->eighth(); // 8
```
### `ninth`
Retrieve item at the ninth index.
```php
$data = new Collection([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
$data->ninth(); // 9
```
### `tenth`
Retrieve item at the tenth index.
```php
$data = new Collection([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
$data->tenth(); // 10
```
### `getNth`
Retrieve item at the nth item.
```php
$data = new Collection([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]);
$data->getNth(11); // 11
```
### `before`
Get the previous item from the collection.
```php
$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.
```php
$collection = collect([1,2,3]);
$currentItem = 1;
$collection->before($currentItem, $collection->last()); // return 3;
```
### `catch`
See [`Try`](#try)
### `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.
```php
collect(['A', 'A', 'B', 'A'])->chunkBy(function($item) {
return $item == 'A';
}); // return Collection([['A', 'A'],['B'], ['A']])
```
### `collectBy`
Get an item at a given key, and collect it.
```php
$collection = collect([
'foo' => [1, 2, 3],
'bar' => [4, 5, 6],
]);
$collection->collectBy('foo'); // Collection([1, 2, 3])
```
You can also pass a second parameter to be used as a fallback.
```php
$collection = collect([
'foo' => [1, 2, 3],
'bar' => [4, 5, 6],
]);
$collection->collectBy('baz', ['Nope']); // Collection(['Nope'])
```
### `containsAny`
Will return `true` if one or more of the given values exist in the collection.
```php
$collection = collect(['a', 'b', 'c']);
$collection->containsAny(['b', 'c', 'd']); // returns true
$collection->containsAny(['c', 'd', 'e']); // returns true
$collection->containsAny(['d', 'e', 'f']); // returns false
$collection->containsAny([]); // returns false
```
### `containsAll`
Will return `true` if all given values exist in the collection.
```php
$collection = collect(['a', 'b', 'c']);
$collection->containsAll(['b', 'c',]); // returns true
$collection->containsAll(['c', 'd']); // returns false
$collection->containsAll(['d', 'e']); // returns false
$collection->containsAll([]); // returns true
```
### `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.
```php
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 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.
```php
[$name, $role] = collect($user)->extract('name', 'role.name');
```
### `filterMap`
Map a collection and remove falsy values in one go.
```php
$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.
```php
$collection = collect([1, 2, 3, 4, 5, 6])->firstOrFail();
$collection->toArray(); // returns [1]
collect([])->firstOrFail(); // throws Spatie\CollectionMacros\Exceptions\CollectionItemNotFound
```
### `firstOrPush`
Retrieve the first item using the callable given as the first parameter. If no value exists, push the value of the second
parameter into the collection. You can pass a callable as the second parameter.
This method is really useful when dealing with cached class properties, where you want to store a value retrieved from an API or computationally expensive function in a collection to be used multiple times.
```php
$collection = collect([1, 2, 3])->firstOrPush(fn($item) => $item === 4, 4);
$collection->toArray(); // returns [1, 2, 3, 4]
```
Occasionally, you'll want to specify the target collection to be pushed to. You may pass this as a third parameter.
```php
$collection = collect([1, 2, 3]);
$collection->filter()->firstOrPush(fn($item) => $item === 4, 4, $collection);
$collection->toArray(); // returns [1, 2, 3, 4]
```
### `fromPairs`
Transform a collection into an associative array form collection item.
```php
$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.
```php
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.
```php
$posts->groupByModel('category');
// [
// [$categoryA, [/*...$posts*/]],
// [$categoryB, [/*...$posts*/]],
// ];
```
Full signature: `groupByModel($callback, $preserveKeys, $modelKey, $itemsKey)`
### `head`
Retrieves first item from the collection.
```php
$collection = collect([1,2,3]);
$collection->head(); // return 1
$collection = collect([]);
$collection->head(); // return null
```
### `if`
The `if` macro can help branch collection chains. This is the signature of this macro:
```php
if(mixed $if, mixed $then = null, mixed $else = null): mixed
```
`$if`, `$then` and `$else` can be any type. If a closure is passed to any of these parameters, then that closure will be executed and the macro will use its results.
When `$if` returns a truthy value, then `$then` will be returned, otherwise `$else` will be returned.
Here are some examples:
```php
collect()->if(true, then: true, else: false); // returns true
collect()->if(false, then: true, else: false); // returns false
```
When a closure is passed to `$if`, `$then` or `$else`, the entire collection will be passed as an argument to that closure.
```php
// the `then` closure will be executed
// the first element of the returned collection now contains "THIS IS THE VALUE"
$collection = collect(['this is a value'])
->if(
fn(Collection $collection) => $collection->contains('this is a value'),
then: fn(Collection $collection) => $collection->map(fn(string $item) => strtoupper($item)),
else: fn(Collection $collection) => $collection->map(fn(string $item) => Str::kebab($item))
);
// the `else` closure will be executed
// the first element of the returned collection now contains "this-is-another-value"
$collection = collect(['this is another value'])
->if(
fn(Collection $collection) => $collection->contains('this is a value'),
then: fn(Collection $collection) => $collection->map(fn(string $item) => strtoupper($item)),
else: fn(Collection $collection) => $collection->map(fn(string $item) => Str::kebab($item))
);
```
### `ifAny`
Executes the passed callable if the collection isn't empty. The entire collection will be returned.
```php
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.
```php
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';
});
```
### `insertAfter`
Inserts an item after the first occurrence of a given item and returns the updated Collection instance.
Optionally a key can be given.
```php
collect(['zero', 'two', 'three'])->insertAfter('zero', 'one');
// Collection contains ['zero', 'one', 'two', 'three']
collect(['zero' => 0, 'two' => 2, 'three' => 3]->insertAfter(0, 5, 'five');
// Collection contains ['zero' => 0, 'five' => 5, 'two' => 2, 'three' => 3]
```
### `insertAfterKey`
Inserts an item after a given key and returns the updated Collection instance.
Optionally a key for the new item can be given.
```php
collect(['zero', 'two', 'three'])->insertAfterKey(0, 'one');
// Collection contains ['zero', 'one', 'two', 'three']
collect(['zero' => 0, 'two' => 2, 'three' => 3]->insertAfterKey('zero', 5, 'five');
// Collection contains ['zero' => 0, 'five' => 5, 'two' => 2, 'three' => 3]
```
### `insertAt`
Inserts an item at a given index and returns the updated Collection instance. Optionally a key can be given.
```php
collect(['zero', 'two', 'three'])->insertAt(1, 'one');
// Collection contains ['zero', 'one', 'two', 'three']
collect(['zero' => 0, 'two' => 2, 'three' => 3]->insertAt(1, 5, 'five');
// Collection contains ['zero' => 0, 'five' => 5, 'two' => 2, 'three' => 3]
```
### `insertBefore`
Inserts an item before the first occurrence of a given item and returns the updated Collection instance.
Optionally a key can be given.
```php
collect(['zero', 'two', 'three'])->insertBefore('two', 'one');
// Collection contains ['zero', 'one', 'two', 'three']
collect(['zero' => 0, 'two' => 2, 'three' => 3]->insertBefore(2, 5, 'five');
// Collection contains ['zero' => 0, 'five' => 5, 'two' => 2, 'three' => 3]
```
### `insertBeforeKey`
Inserts an item before a given key and returns the updated Collection instance.
Optionally a key for the new item can be given.
```php
collect(['zero', 'two', 'three'])->insertBeforeKey(1, 'one');
// Collection contains ['zero', 'one', 'two', 'three']
collect(['zero' => 0, 'two' => 2, 'three' => 3]->insertBeforeKey('two', 5, 'five');
// Collection contains ['zero' => 0, 'five' => 5, 'two' => 2, 'three' => 3]
```
### `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.
```php
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
```
### `path`
Returns an item from the collection with multidimensional data using "dot" notation.
Works the same way as native Collection's `pull` method, but without removing an item from the collection.
```php
$collection = new Collection([
'foo' => [
'bar' => [
'baz' => 'value',
]
]
]);
$collection->path('foo.bar.baz') // 'value'
```
### `pluckMany`
Returns a collection with only the specified keys.
```php
$collection = collect([
['a' => 1, 'b' => 10, 'c' => 100],
['a' => 2, 'b' => 20, 'c' => 200],
]);
$collection->pluckMany(['a', 'b']);
// returns
// collect([
// ['a' => 1, 'b' => 10],
// ['a' => 2, 'b' => 20],
// ]);
```
### `pluckToArray`
Returns array of values of a given key.
```php
$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.
```php
$collection = collect([
['id' => 1],
['id' => 2],
['id' => 3],
]);
$collection
->prioritize(function(array $item) {
return $item['id'] === 2;
})
->pluck('id')
->toArray(); // returns [2, 1, 3]
```
### `recursive`
Convert an array and its children to collection using recursion.
```php
collect([
'item' => [
'children' => []
]
])->recursive();
// subsequent arrays are now collections
```
### `rotate`
Rotate the items in the collection with given offset
```php
$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.
```php
$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)`
### `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.
```php
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)`.
```php
collect([1, 2, 3])->tail(); // return collect([2, 3])
```
### `toPairs`
Transform a collection into an array with pairs.
```php
$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.
```php
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'],
// ]
```
### `weightedRandom`
Returns a random item by a weight. In this example, the item with `a` has the most chance to get picked, and the item with `c` the least.
```php
// pass the field name that should be used as a weight
$randomItem = collect([
['value' => 'a', 'weight' => 30],
['value' => 'b', 'weight' => 20],
['value' => 'c', 'weight' => 10],
])->weightedRandom('weight');
```
Alternatively, you can pass a callable to get the weight.
```php
$randomItem = collect([
['value' => 'a', 'weight' => 30],
['value' => 'b', 'weight' => 20],
['value' => 'c', 'weight' => 10],
])->weightedRandom(function(array $item) {
return $item['weight'];
});
```
### `withSize`
Create a new collection with the specified amount of items.
```php
Collection::withSize(1)->toArray(); // return [1];
Collection::withSize(5)->toArray(); // return [1,2,3,4,5];
```
## License
The MIT License (MIT). Please see [License File](LICENSE) for more information.