Documentation

config()

Load a php config file.

$config['key'] = 'value';
// EOF

return [
    'key' => 'value',
];

Parameters

$path : string

createMap()

Shorthand for putting together [key => value] maps.

$users = getUsers();

// Assuming users are sorted.
$options = Arrays::createMap($users, 'id', 'name', 'Choose a user');

// Hacky post-sort solution.
$options = Arrays::createMap($users, 'id', 'name');
asort($options);
$options = ['' => 'Choose a user' ] + $options;

Parameters

$items : iterable<string|int, mixed>

$key : string

$name : string

$select : string|null = null

Include a 'choose' option

createMultisort()

Combine a set of sorts into a multisort.

// Use default direction for all modes.
$sort = Arrays::createMultisort(['group', 'name']);

// Explicit directions per mode.
$sort = Arrays::createMultisort([
     'group' => SORT_DESC,
     'name' => SORT_ASC,
]);

Parameters

$modes : array<string|int, mixed>

[ name => SORT ]

createSort()

Create a comparator function.

Parameters

$dir : int = SORT_ASC

SORT_ASC|SORT_DESC

$mode : string|null = null

null => 'default'

explodeKeys()

Explode a flat array into a nested array based on the keys.

// From this:
[ 'key.sub.value' => $item ]

// To this:
[ 'key' => [ 'sub' => [ 'value' => $item ] ] ]

Parameters

$array : array<string|int, mixed>

$glue : string = '.'

$index : string|int = ''

fill()

Fill an array with the results of a callable.

Arrays::fill(5, function(&$index) {
    $index = 4 - $index;
    return $index;
});
// => [4 => 0, 3 => 1, 2 => 2, 1 => 3, 0 => 4]

Parameters

$size : int

$fn : callable

(&$index) => $value

fillIntersectionKeys()

Produce a keyed set of 'keys' with values from 'array' otherwise filled with the 'fill' value.

$output = fillIntersectionKeys(['a', 'b'], ['b' => 1, 'c' => 2], 0);
// => ['a' => 0, 'b' => 1]

Parameters

$keys : array<string|int, mixed>

$array : array<string|int, mixed>

$fill : mixed = null

fillKeyed()

Fill a keyed array with the results of a callable.

Arrays::fillKeyed(5, fn($index) => [4 - $index, $index]);
// => [4 => 0, 3 => 1, 2 => 2, 1 => 3, 0 => 4]

Parameters

$size : int

$fn : callable

($index) => [$key, $value]

filterKeys()

Reduce the array to a subset, as defined by the keys parameter.

Parameters

$array : array<string|int, T>

$keys : array<string|int, string>

$fill : bool = false

Replace missing keys with null.

Tags

template

filterRecursive()

Filter multi-dimensional arrays.

$arr = [ 'a', '', 'c' ];
$filtered = array_filter($arr);
// => [ 0 => 'a', 2 => 'c' ]

Parameters

$array : array<string|int, T>

$callback : callable|null = null

$mode : int|null = null

LEAVES_ONLY (default), SELF_FIRST, CHILD_FIRST, DISCARD_EMPTY_ARRAYS

Tags

template

find()

Find a matching item.

// You can write:
Arrays::find($stuff, fn($item) => $item->id === 100);

// Or maybe:
Arrays::find($stuff, fn($item, key) => $key === 12 and $item->name === 12);

Parameters

$iterable : array<string|int, T>|iterable<string|int, T>

$fn : callable

($value, $key) => bool

Tags

template

findKey()

Find a matching item key.

Parameters

$iterable : array<string|int, T>|iterable<string|int, T>

$fn : callable

($value, $key) => bool

Tags

template

first()

First item in the iterable.

Parameters

$iterable : array<string|int, T>|iterable<string|int, T>

Tags

template

firstKey()

Get the first key of an iterable.

Parameters

$iterable : iterable<string|int, mixed>

firstPair()

Get the first key + value of an iterable.

Parameters

$iterable : iterable<string|int, mixed>

flatten()

Flat arrays, with optional key support.

Parameters

$array : iterable<string|int, mixed>

$keys : bool = false

$depth : int = 25

flattenKeys()

Flatten the keys of an array with a 'glue'.

[ 'abc' => [
    'def' => 123,
    'ghi' => 567,
]]

[
    'abc.def' => 123,
    'abc.ghi' => 567,
]

Parameters

$array : array<string|int, mixed>

$glue : string = '.'

implodeWithKeys()

Join together both key and values of an array.

Parameters

$array : array<string|int, mixed>

$outer_glue : string = ''

$inner_glue : string = ''

indexOf()

Find the numeric index of an associative item.

Parameters

$array : array<string|int, mixed>

$key : string

isAssociated()

Is this an associated/keyed array.

Parameters

$array : mixed

isNumeric()

Is this array a numeric/non-associated array.

Parameters

$array : mixed

last()

Last item in the iterable.

Parameters

$iterable : array<string|int, T>|iterable<string|int, T>

Tags

template

lastKey()

Get the last key of an iterable.

Parameters

$iterable : iterable<string|int, mixed>

lastPair()

Get the last key + value of an iterable.

Parameters

$iterable : iterable<string|int, mixed>

map()

A basic `array_map` that accepts iterables.

Parameters

$array : iterable<string|int, mixed>

$fn : callable

(item) => item

mapRecursive()

A recursive version of `array_map`.

Parameters

$array : array<string|int, mixed>

$fn : callable

($value, $key) => $value

$mode : int = self::LEAVES_ONLY

LEAVES_ONLY (default), SELF_FIRST, CHILD_FIRST

mapWithKeys()

Like `array_map` but includes a 'key' argument.

// Basic usage
Arrays::mapWithKeys($list, fn($item, $key) => $key . $item);

// OR to modify keys
Arrays::mapWithKeys($list, function($item, &$key) {
    $key = $item->id;
    return $item;
});

Parameters

$array : iterable<string|int, mixed>

$fn : callable

(item, key) => item

mergeKeyed()

Merge arrays while preserving keys.

array_merge([3 => 'one'], [3 => 'two'])
// => ['one', two']

mergeKeyed([3 => 'one'], [3 => 'two'])
// => [3 => 'two']

Parameters

$arrays : array<string|int, mixed>

multisort()

Multisort an array using the {@see Sortable} interface.

Parameters

$array : array<string|int, mixed>

$preserve_keys : bool

$modes : array<string|int, string>

[ name => SORT ]

Tags

see

createMultisort()

multisorted()

Multisort an array and return it.

Parameters

$array : array<string|int, T>

$preserve_keys : bool

$modes : array<string|int, string>

[ name => SORT ]

Tags

see

createMultisort()

template

normalizeOptions()

Normalise a list of options with mixed associated / values.

$options = [
    'field-1',
    'field-2' => 'DESC',
    'field-3',
    'field-4' => 'DESC',
];
$options = Arrays::normalizeOptions($options, 'ASC');
// Returns:
[
    'field-1' => 'ASC',
    'field-2' => 'DESC',
    'field-3' => 'ASC',
    'field-4' => 'DESC',
];

Parameters

$items : iterable<string|int, mixed>

$default : mixed

reduce()

Array reduce - with keys.

Arrays::reduce($list, fn($sum, $item, $key) => $sum + $key, 0);

Parameters

$iterable : iterable<string|int, mixed>

$fn : callable

(sum, item, key) => array

$initial : mixed|null = null

reverse()

Create a reversed iterator of an array/traversable.

Parameters

$array : iterable<string|int, T>

Tags

template

reverseReduce()

Reduce an array in reverse.

Parameters

$array : iterable<string|int, mixed>

$fn : callable

(carry, value, key)

$initial : T|null = null

Tags

template

shuffle()

Shuffle an array, optionally preserving the keys.

Parameters

$array : array<string|int, T>|iterable<string|int, T>

$preserve_keys : bool = false

Tags

template

sort()

Sort an array using the {@see Sortable} interface.

Parameters

$array : array<string|int, mixed>

$preserve_keys : bool = false

$dir : int = SORT_ASC

SORT_ASC|SORT_DESC

$mode : string|null = null

null => 'default'

sorted()

Sort an array and return it.

Parameters

$array : array<string|int, T>

$preserve_keys : bool = false

$dir : int = SORT_ASC

SORT_ASC|SORT_DESC

$mode : string|null = null

null => 'default'

Tags

template

toArray()

Make everything an array, all the way down.

Parameters

$array : object|array<string|int, mixed>

$recurse : bool = true

• recurse into nested arrays

value()

Query an array.

[
   'items' => [
     [ 'subitem' => [ 'id' => 123, 'list' => [1,2,3] ] ],
     [ 'subitem' => [ 'id' => 456, 'list' => [4,5,6] ] ],
   ],
   'options' => [
      'host' => 'localhost',
      'port' => 5060,
   ]
]

// A query `items.subitem.id` would return:
=> [ 123, 456 ]

// Or `items.subitem.list`:
=> [ [1, 2, 3], [4, 5, 6] ]

// Perhaps `options`:
=> [ 'host' => 'localhost', 'port' => '5060' ]

// And `options.host`:
=> 'localhost'

Parameters

$array : array<string|int, mixed>

$query : string

zip()

An `array_map` that accepts iterables.

Parameters

$arrays : iterable<string|int, mixed>