Array functions
All array functions live in the Spatie\Piper\Arr namespace. Import them individually or in groups.
use function Spatie\Piper\Arr\{filter, map, values};
Each function takes its subject as the first argument, so it slots naturally into a pipe. The reference below lists every available function in alphabetical order. Click a name to jump straight to its description.
##after
Returns the item after the given value.
[1, 2, 3] |> after(2); // 3
##average
Returns the average of the given values.
[['score' => 10], ['score' => 20]] |> average('score'); // 15
##avg
Alias of average.
[['score' => 10], ['score' => 20]] |> avg('score'); // 15
##before
Returns the item before the given value.
[1, 2, 3] |> before(2); // 1
##chunk
Breaks the array into chunks of the given size.
[1, 2, 3, 4, 5] |> chunk(2); // [[1, 2], [3, 4], [5]]
##chunkWhile
Breaks the array into chunks while the callback returns true.
str_split('AABB') |> chunkWhile(fn (string $value, int $key, array $chunk) => $value === end($chunk)); // [['A', 'A'], ['B', 'B']]
##collapse
Collapses an array of arrays into a single array.
[[1, 2], [3, 4]] |> collapse(); // [1, 2, 3, 4]
##collapseWithKeys
Collapses an array of keyed arrays while preserving keys.
[['name' => 'Taylor'], ['role' => 'admin']] |> collapseWithKeys(); // ['name' => 'Taylor', 'role' => 'admin']
##combine
Combines the array values as keys with another set of values.
['name', 'role'] |> combine(['Taylor', 'admin']); // ['name' => 'Taylor', 'role' => 'admin']
##concat
Appends the given values to the end of the array.
[1, 2] |> concat([3, 4]); // [1, 2, 3, 4]
##contains
Determines whether the array contains the given value or passes the given truth test.
['Taylor', 'Abigail'] |> contains('Taylor'); // true
##containsStrict
Determines whether the array strictly contains the given value.
[1, 2, 3] |> containsStrict('1'); // false
##count
Returns the number of items in the array.
[1, 2, 3] |> count(); // 3
##countBy
Counts values by the result of the given callback.
['laravel', 'php', 'piper'] |> countBy(fn (string $value) => strlen($value)); // [7 => 1, 3 => 1, 5 => 1]
##crossJoin
Returns the Cartesian product of the array and the given arrays.
[1, 2] |> crossJoin(['a', 'b']); // [[1, 'a'], [1, 'b'], [2, 'a'], [2, 'b']]
##diff
Returns the values that are not present in the given array.
['a', 'b', 'c'] |> diff(['b']); // [0 => 'a', 2 => 'c']
##diffAssoc
Returns key/value pairs that are not present in the given array.
['a' => 1, 'b' => 2] |> diffAssoc(['a' => 1]); // ['b' => 2]
##diffAssocUsing
Returns key/value pairs that are not present after comparing keys with a callback.
['a' => 1, 'b' => 2] |> diffAssocUsing(['A' => 1], 'strcasecmp'); // ['b' => 2]
##diffKeys
Returns items whose keys are not present in the given array.
['a' => 1, 'b' => 2] |> diffKeys(['a' => 9]); // ['b' => 2]
##diffKeysUsing
Returns items whose keys are not present after comparing keys with a callback.
['a' => 1, 'b' => 2] |> diffKeysUsing(['A' => 9], 'strcasecmp'); // ['b' => 2]
##diffUsing
Returns values that are not present after comparing values with a callback.
['a', 'b'] |> diffUsing(['A'], 'strcasecmp'); // [1 => 'b']
##doesntContain
Determines whether the array does not contain the given value or pass the given truth test.
['Taylor', 'Abigail'] |> doesntContain('Jess'); // true
##doesntContainStrict
Determines whether the array does not strictly contain the given value.
[1, 2, 3] |> doesntContainStrict('1'); // true
##dot
Flattens a multidimensional array using dot notation.
['user' => ['name' => 'Taylor']] |> dot(); // ['user.name' => 'Taylor']
##duplicates
Returns duplicate values from the array.
['a', 'b', 'a'] |> duplicates(); // [2 => 'a']
##duplicatesStrict
Returns duplicate values using strict comparisons.
[1, '1', 1] |> duplicatesStrict(); // [2 => 1]
##each
Iterates over each item in the array.
[1, 2, 3] |> each(fn (int $value) => logger($value));
##eachSpread
Iterates over nested item values by spreading them into the callback.
[[1, 2], [3, 4]] |> eachSpread(fn (int $a, int $b) => logger($a + $b));
##ensure
Verifies that every item in the array is of the expected type.
[1, 2, 3] |> ensure('int'); // [1, 2, 3]
##every
Determines whether all items pass the given truth test.
[1, 2, 3] |> every(fn (int $value) => $value > 0); // true
##except
Returns all items except those with the given keys.
['name' => 'Taylor', 'role' => 'admin'] |> except('role'); // ['name' => 'Taylor']
##filter
Filters the array using the given callback.
[1, 2, 3, 4] |> filter(fn (int $value) => $value > 2); // [2 => 3, 3 => 4]
##first
Returns the first item that passes the given truth test.
[1, 2, 3] |> first(fn (int $value) => $value > 1); // 2
##firstOrFail
Returns the first item or throws when no item is found.
[1, 2, 3] |> firstOrFail(fn (int $value) => $value > 2); // 3
##firstWhere
Returns the first item matching the given key/value constraint.
[['score' => 98], ['score' => 91]] |> firstWhere('score', '>', 95); // ['score' => 98]
##flatMap
Maps over the array and flattens the result by one level.
[1, 2] |> flatMap(fn (int $value) => [$value, $value * 10]); // [1, 10, 2, 20]
##flatten
Flattens a multidimensional array.
[1, [2, [3]]] |> flatten(); // [1, 2, 3]
##flip
Swaps the array keys with their values.
['name' => 'Taylor'] |> flip(); // ['Taylor' => 'name']
##forget
Returns a copy of the array without the given key.
['name' => 'Taylor', 'role' => 'admin'] |> forget('role'); // ['name' => 'Taylor']
##forPage
Returns the items that would appear on the given page.
[1, 2, 3, 4] |> forPage(2, 2); // [2 => 3, 3 => 4]
##fromJson
Decodes a JSON string into an array.
fromJson('{"name":"Taylor"}'); // ['name' => 'Taylor']
##get
Returns the value for the given key, or a default value.
['name' => 'Taylor'] |> get('name'); // 'Taylor'
##getOrPut
Returns an existing value or evaluates and returns a default value.
['name' => 'Taylor'] |> getOrPut('role', 'admin'); // 'admin'
##groupBy
Groups the array items by a given key or callback.
[['team' => 'core', 'name' => 'Taylor'], ['team' => 'docs', 'name' => 'Jess']] |> groupBy('team'); // ['core' => [...], 'docs' => [...]]
##has
Determines whether the given key exists in the array.
['name' => 'Taylor'] |> has('name'); // true
##hasAny
Determines whether any of the given keys exist in the array.
['name' => 'Taylor'] |> hasAny('email', 'name'); // true
##hasMany
Determines whether more than one item passes the given truth test.
[1, 2, 3] |> hasMany(fn (int $value) => $value > 1); // true
##hasSole
Determines whether exactly one item passes the given truth test.
[1, 2, 3] |> hasSole(fn (int $value) => $value === 2); // true
##implode
Joins array values into a string.
[['name' => 'Taylor'], ['name' => 'Abigail']] |> implode('name', ', '); // 'Taylor, Abigail'
##intersect
Returns the values that are present in the given array.
['a', 'b'] |> intersect(['b', 'c']); // [1 => 'b']
##intersectAssoc
Returns key/value pairs that are present in the given array.
['a' => 1, 'b' => 2] |> intersectAssoc(['a' => 1]); // ['a' => 1]
##intersectAssocUsing
Returns key/value pairs that are present after comparing keys with a callback.
['a' => 1, 'b' => 2] |> intersectAssocUsing(['A' => 1], 'strcasecmp'); // ['a' => 1]
##intersectByKeys
Returns items whose keys are present in the given array.
['a' => 1, 'b' => 2] |> intersectByKeys(['b' => 9]); // ['b' => 2]
##intersectUsing
Returns values that are present after comparing values with a callback.
['a', 'b'] |> intersectUsing(['A'], 'strcasecmp'); // [0 => 'a']
##isEmpty
Determines whether the array is empty.
[] |> isEmpty(); // true
##isNotEmpty
Determines whether the array is not empty.
[1] |> isNotEmpty(); // true
##join
Joins array values with a final glue string.
['a', 'b', 'c'] |> join(', ', ' and '); // 'a, b and c'
##keyBy
Keys the array by the given key or callback.
[['id' => 1, 'name' => 'Taylor']] |> keyBy('id'); // [1 => ['id' => 1, 'name' => 'Taylor']]
##keys
Returns all keys from the array.
['name' => 'Taylor', 'role' => 'admin'] |> keys(); // ['name', 'role']
##last
Returns the last item that passes the given truth test.
[1, 2, 3] |> last(fn (int $value) => $value < 3); // 2
##make
Converts the given value into an array.
make('Taylor'); // ['Taylor']
##map
Maps each item using the given callback.
[1, 2, 3] |> map(fn (int $value) => $value * 2); // [2, 4, 6]
##mapInto
Maps each item into a new instance of the given class.
$users |> mapInto(UserData::class); // [UserData, UserData, ...]
##mapSpread
Maps nested item values by spreading them into the callback.
[[1, 2], [3, 4]] |> mapSpread(fn (int $a, int $b) => $a + $b); // [3, 7]
##mapToDictionary
Groups values returned by the callback into a dictionary.
$users |> mapToDictionary(fn (array $user) => [$user['team'] => $user['name']]); // ['core' => ['Taylor']]
##mapToGroups
Groups values returned by the callback.
$users |> mapToGroups(fn (array $user) => [$user['team'] => $user['name']]); // ['core' => ['Taylor']]
##mapWithKeys
Maps items into key/value pairs.
$users |> mapWithKeys(fn (array $user) => [$user['email'] => $user['name']]); // ['taylor@example.com' => 'Taylor']
##max
Returns the maximum value for a given key or callback.
[['score' => 10], ['score' => 20]] |> max('score'); // 20
##median
Returns the median value for a given key.
[1, 1, 2, 4] |> median(); // 1.5
##merge
Merges the given array into the current array.
['a'] |> merge(['b']); // ['a', 'b']
##mergeRecursive
Recursively merges the given array into the current array.
['a' => ['x']] |> mergeRecursive(['a' => ['y']]); // ['a' => ['x', 'y']]
##min
Returns the minimum value for a given key or callback.
[['score' => 10], ['score' => 20]] |> min('score'); // 10
##mode
Returns the most frequently occurring value for a given key.
[1, 1, 2, 2, 3] |> mode(); // [1, 2]
##multiply
Creates copies of the array items the given number of times.
['a', 'b'] |> multiply(2); // ['a', 'b', 'a', 'b']
##nth
Returns every nth item from the array.
[1, 2, 3, 4, 5] |> nth(2); // [1, 3, 5]
##only
Returns only the items with the given keys.
['name' => 'Taylor', 'role' => 'admin'] |> only('name'); // ['name' => 'Taylor']
##pad
Pads the array to the given size with a value.
[1, 2] |> pad(4, 0); // [1, 2, 0, 0]
##partition
Separates items that pass the truth test from those that do not.
[1, 2, 3, 4] |> partition(fn (int $value) => $value % 2 === 0); // [[1 => 2, 3 => 4], [0 => 1, 2 => 3]]
##percentage
Returns the percentage of items that pass the given truth test.
[1, 2, 3, 4] |> percentage(fn (int $value) => $value > 2); // 50.0
##pluck
Retrieves all values for a given key.
[['name' => 'Taylor'], ['name' => 'Abigail']] |> pluck('name'); // ['Taylor', 'Abigail']
##pop
Returns and removes the last item from a copy of the array.
[1, 2, 3] |> pop(); // 3
##prepend
Adds an item to the beginning of the array.
['b', 'c'] |> prepend('a'); // ['a', 'b', 'c']
##pull
Returns the value for a key from a copy of the array.
['name' => 'Taylor'] |> pull('name'); // 'Taylor'
##push
Adds one or more items to the end of the array.
[1, 2] |> push(3, 4); // [1, 2, 3, 4]
##put
Sets the given key and value on the array.
['name' => 'Taylor'] |> put('role', 'admin'); // ['name' => 'Taylor', 'role' => 'admin']
##random
Returns one or more random items from the array.
['a', 'b', 'c'] |> random(); // 'b'
##range
Creates an array containing a range of numbers.
range(1, 3); // [1, 2, 3]
##reduce
Reduces the array to a single value.
[1, 2, 3] |> reduce(fn (int $carry, int $value) => $carry + $value, 0); // 6
##reduceSpread
Reduces the array to multiple aggregate values.
[1, 2, 3] |> reduceSpread(fn (int $sum, int $count, int $value) => [$sum + $value, $count + 1], 0, 0); // [6, 3]
##reduceWithKeys
Reduces the array to a single value while receiving keys.
['a' => 1, 'b' => 2] |> reduceWithKeys(fn (int $carry, int $value, string $key) => $carry + $value, 0); // 3
##reject
Filters out items using the given callback.
[1, 2, 3, 4] |> reject(fn (int $value) => $value > 2); // [0 => 1, 1 => 2]
##replace
Replaces items in the array with items from the given array.
['name' => 'Taylor'] |> replace(['name' => 'Abigail']); // ['name' => 'Abigail']
##replaceRecursive
Recursively replaces items in the array with items from the given array.
['user' => ['name' => 'Taylor']] |> replaceRecursive(['user' => ['name' => 'Abigail']]); // ['user' => ['name' => 'Abigail']]
##reverse
Reverses the order of the array items.
[1, 2, 3] |> reverse(); // [2 => 3, 1 => 2, 0 => 1]
##search
Returns the key of the first item matching the value or callback.
['a' => 1, 'b' => 2] |> search(2); // 'b'
##select
Selects the given keys from every item in the array.
$users |> select(['id', 'name']); // [['id' => 1, 'name' => 'Taylor'], ...]
##shift
Returns and removes the first item from a copy of the array.
[1, 2, 3] |> shift(); // 1
##shuffle
Randomly shuffles the array items.
[1, 2, 3] |> shuffle(); // [2, 3, 1]
##skip
Returns the array without the first given number of items.
[1, 2, 3, 4] |> skip(2); // [2 => 3, 3 => 4]
##skipUntil
Skips items until the given value or callback is reached.
[1, 2, 3, 4] |> skipUntil(3); // [2 => 3, 3 => 4]
##skipWhile
Skips items while the given callback returns true.
[1, 2, 3, 4] |> skipWhile(fn (int $value) => $value < 3); // [2 => 3, 3 => 4]
##slice
Returns a slice of the array starting at the given offset.
[1, 2, 3, 4] |> slice(1, 2); // [1 => 2, 2 => 3]
##sliding
Returns a sliding window view of the array.
[1, 2, 3, 4] |> sliding(3); // [[1, 2, 3], [2, 3, 4]]
##sole
Returns the only item matching the given truth test.
[1, 2, 3] |> sole(fn (int $value) => $value === 2); // 2
##some
Alias of contains for truth tests.
[1, 2, 3] |> some(fn (int $value) => $value === 2); // true
##sort
Sorts the array values.
[3, 1, 2] |> sort() |> values(); // [1, 2, 3]
##sortBy
Sorts the array by a given key or callback.
$users |> sortBy('score') |> values(); // lowest score first
##sortByDesc
Sorts the array descending by a given key or callback.
$users |> sortByDesc('score') |> values(); // highest score first
##sortDesc
Sorts the array values in descending order.
[3, 1, 2] |> sortDesc() |> values(); // [3, 2, 1]
##sortKeys
Sorts the array by its keys.
['b' => 2, 'a' => 1] |> sortKeys(); // ['a' => 1, 'b' => 2]
##sortKeysDesc
Sorts the array by its keys in descending order.
['a' => 1, 'b' => 2] |> sortKeysDesc(); // ['b' => 2, 'a' => 1]
##sortKeysUsing
Sorts the array keys using a callback.
['b' => 2, 'a' => 1] |> sortKeysUsing('strnatcmp'); // ['a' => 1, 'b' => 2]
##splice
Returns a slice removed from the array.
[1, 2, 3, 4] |> splice(1, 2); // [2, 3]
##split
Splits the array into the given number of groups.
[1, 2, 3, 4, 5] |> split(2); // [[1, 2, 3], [4, 5]]
##splitIn
Splits the array into the given number of groups, filling groups as evenly as possible.
[1, 2, 3, 4, 5] |> splitIn(2); // [[1, 2, 3], [4, 5]]
##sum
Returns the sum of the given values.
[['score' => 10], ['score' => 20]] |> sum('score'); // 30
##take
Returns the first or last number of items.
[1, 2, 3, 4] |> take(2); // [1, 2]
##takeUntil
Returns items until the given value or callback is reached.
[1, 2, 3, 4] |> takeUntil(3); // [1, 2]
##takeWhile
Returns items while the given callback returns true.
[1, 2, 3, 4] |> takeWhile(fn (int $value) => $value < 3); // [1, 2]
##tap
Passes the array to a callback and returns the array.
[1, 2, 3] |> tap(fn (array $items) => logger($items)); // [1, 2, 3]
##times
Creates an array by invoking a callback a given number of times.
times(3, fn (int $number) => $number * 2); // [2, 4, 6]
##toArray
Converts the value to a plain array.
[1, 2, 3] |> toArray(); // [1, 2, 3]
##toJson
Converts the array to JSON.
['name' => 'Taylor'] |> toJson(); // '{"name":"Taylor"}'
##toPrettyJson
Converts the array to pretty-printed JSON.
['name' => 'Taylor'] |> toPrettyJson(); // "{\n \"name\": \"Taylor\"\n}"
##transform
Maps each item and returns the transformed array.
[1, 2] |> transform(fn (int $value) => $value * 10); // [10, 20]
##undot
Expands a dot-notated array into a multidimensional array.
['user.name' => 'Taylor'] |> undot(); // ['user' => ['name' => 'Taylor']]
##union
Adds the given array to the current array without replacing existing keys.
['a' => 1] |> union(['a' => 2, 'b' => 3]); // ['a' => 1, 'b' => 3]
##unique
Returns the unique items in the array.
['a', 'b', 'a'] |> unique(); // [0 => 'a', 1 => 'b']
##uniqueStrict
Returns the unique items using strict comparisons.
[1, '1', 1] |> uniqueStrict(); // [0 => 1, 1 => '1']
##unless
Runs the callback unless the given value is truthy.
[1] |> unless(false, fn (array $items) => [...$items, 2]); // [1, 2]
##unlessEmpty
Runs the callback unless the array is empty.
[1] |> unlessEmpty(fn (array $items) => [...$items, 2]); // [1, 2]
##unlessNotEmpty
Runs the callback unless the array is not empty.
[] |> unlessNotEmpty(fn (array $items) => ['empty']); // ['empty']
##unwrap
Returns the given value without wrapping it in an array.
unwrap(['Taylor']); // ['Taylor']
##value
Returns the first item value for a given key.
[['name' => 'Taylor'], ['name' => 'Abigail']] |> value('name'); // 'Taylor'
##values
Returns the array with consecutive integer keys.
['a' => 'Taylor', 'b' => 'Abigail'] |> values(); // ['Taylor', 'Abigail']
##when
Runs the callback when the given value is truthy.
[1] |> when(true, fn (array $items) => [...$items, 2]); // [1, 2]
##whenEmpty
Runs the callback when the array is empty.
[] |> whenEmpty(fn (array $items) => ['empty']); // ['empty']
##whenNotEmpty
Runs the callback when the array is not empty.
[1] |> whenNotEmpty(fn (array $items) => [...$items, 2]); // [1, 2]
##where
Filters items by a key/value pair.
$users |> where('team', 'core'); // users on the core team
##whereBetween
Filters items where a key is between two values.
$users |> whereBetween('score', [90, 100]); // users with scores from 90 to 100
##whereIn
Filters items where a key is present in the given values.
$users |> whereIn('name', ['Taylor', 'Jess']); // matching users
##whereInstanceOf
Filters items by class or type.
$items |> whereInstanceOf(DateTimeImmutable::class); // DateTimeImmutable instances
##whereInStrict
Filters items where a key is strictly present in the given values.
$users |> whereInStrict('id', [1, 2]); // users with matching integer IDs
##whereNotBetween
Filters items where a key is outside two values.
$users |> whereNotBetween('score', [90, 100]); // users outside the score range
##whereNotIn
Filters items where a key is not present in the given values.
$users |> whereNotIn('name', ['Taylor']); // users not named Taylor
##whereNotInStrict
Filters items where a key is strictly not present in the given values.
$users |> whereNotInStrict('id', [1, 2]); // users without those integer IDs
##whereNotNull
Filters items where a key is not null.
$users |> whereNotNull('email'); // users with an email address
##whereNull
Filters items where a key is null.
$users |> whereNull('email'); // users without an email address
##whereStrict
Filters items by a strict key/value comparison.
$users |> whereStrict('active', true); // active users
##wrap
Wraps the given value in an array.
wrap('Taylor'); // ['Taylor']
##zip
Merges together the values of the array with the values of the given arrays.
[1, 2] |> zip(['a', 'b']); // [[1, 'a'], [2, 'b']]