Arrays

Helper functions that can operate on arrays.


all

Returns true if every element in array satisfies the predicate.

Parameters: array $elements, $predicate

Example:

$array = [1, 2];
$all = Arrays::all($array, function ($element) {
    return $element < 3;
});

Result: true


toMap

This method creates associative array using key and value functions on array elements.

Parameters: array $elements, $keyFunction, $valueFunction = null

Example:

$array = range(1, 2);
$map = Arrays::toMap($array, function ($elem) {
    return $elem * 10;
}, function ($elem) {
    return $elem + 1;
});

Result:

Array
(
    [10] => 2
    [20] => 3
)

Note

If $valueFunction is not given Functions::identity() is used.

$users = array(new User('bob'), new User('john'));
$usersByName = Arrays::toMap($users, function ($user) {
    return $user->name;
});

$usersByName will contain associative array with users indexed by their names.

Note

You can Functions::extractField provided by ouzo:

$usersByName = Arrays::toMap($users, Functions::extractField('name'));


flatten

Returns a new array that is a one-dimensional flattening of the given array.

Parameters: array $elements

Example:

$array = [
    'names' => [
        'john',
        'peter',
        'bill'
    ],
    'products' => [
        'cheese',
        ['milk', 'brie']
    ]
];
$flatten = Arrays::flatten($array);

Result:

Array
(
    [0] => john
    [1] => peter
    [2] => bill
    [3] => cheese
    [4] => milk
    [5] => brie
)

findKeyByValue

This method returns a key for the given value.

Parameters: array $elements, $value

Example:

$array = [
    'k1' => 4,
    'k2' => 'd',
    'k3' => 0,
    9 => 'p'
];
$key = Arrays::findKeyByValue($array, 0);

Result: k3


any

Returns true if at least one element in the array satisfies the predicate.

Parameters: array $elements, $predicate

Example:

$array = ['a', true, 'c'];
$any = Arrays::any($array, function ($element) {
    return is_bool($element);
});

Result: true


first

This method returns the first value in the given array .

Parameters: array $elements

Example:

$array = ['one', 'two' 'three'];
$first = Arrays::first($array);

Result: one


last

This method returns the last value in the given array.

Parameters: array $elements

Example:

$array = ['a', 'b', 'c'];
$last = Arrays::last($array);

Result: c


firstOrNull

This method returns the first value or null if array is empty.

Parameters: array $elements

Example:

$array = [];
$return = Arrays::firstOrNull($array);

Result: null


getValue

Returns the element for the given key or a default value otherwise.

Parameters: array $elements, $key, $default = null

Example:

$array = ['id' => 1, 'name' => 'john'];
$value = Arrays::getValue($array, 'name');

Result: john

Example:

$array = ['id' => 1, 'name' => 'john'];
$value = Arrays::getValue($array, 'surname', '--not found--');

Result: --not found--


filterByAllowedKeys

Returns an array containing only the given keys.

Example:

$array = ['a' => 1, 'b' => 2, 'c' => 3];
$filtered = Arrays::filterByAllowedKeys($array, ['a', 'b']);

Result:

Array
(
    [a] => 1
    [b] => 2
)

filterByKeys

Filters array by keys using the predicate.

Example:

$array = ['a1' => 1, 'a2' => 2, 'c' => 3];
$filtered = Arrays::filterByKeys($array, function ($elem) {
    return $elem[0] == 'a';
});

Result:

Array
(
    [a1] => 1
    [a2] => 2
)

groupBy

Groups elements in array using given function. If $orderField is set, grouped elements will be also sorted.

Parameters: array $elements, $keyFunction, $orderField = null

Example:

$obj1 = new stdClass();
$obj1->name = 'a';
$obj1->description = '1';

$obj2 = new stdClass();
$obj2->name = 'b';
$obj2->description = '2';

$obj3 = new stdClass();
$obj3->name = 'b';
$obj3->description = '3';

$array = [$obj1, $obj2, $obj3];
$grouped = Arrays::groupBy($array, Functions::extractField('name'));

Result:

Array
(
    [a] => Array
        (
            [0] => stdClass Object
                (
                    [name] => a
                    [description] => 1
                )

        )

    [b] => Array
        (
            [0] => stdClass Object
                (
                    [name] => b
                    [description] => 2
                )

            [1] => stdClass Object
                (
                    [name] => b
                    [description] => 3
                )

        )

)

orderBy

This method sorts elements in array using order field.

Parameters: array $elements, $orderField

Example:

$obj1 = new stdClass();
$obj1->name = 'a';
$obj1->description = '1';

$obj2 = new stdClass();
$obj2->name = 'c';
$obj2->description = '2';

$obj3 = new stdClass();
$obj3->name = 'b';
$obj3->description = '3';

$array = [$obj1, $obj2, $obj3];
$sorted = Arrays::orderBy($array, 'name');

Result:

Array
(
    [0] => stdClass Object
        (
            [name] => a
            [description] => 1
        )

    [1] => stdClass Object
        (
            [name] => b
            [description] => 3
        )

    [2] => stdClass Object
        (
            [name] => c
            [description] => 2
        )

)

mapKeys

This method maps array keys using the function. It invokes the function for each key in the array and creates a new array containing the keys returned by the function.

Parameters: array $elements, $function

Example:

$array = [
     'k1' => 'v1',
     'k2' => 'v2',
     'k3' => 'v3'
];
$arrayWithNewKeys = Arrays::mapKeys($array, function ($key) {
     return 'new_' . $key;
});

Result:

Array
(
     [new_k1] => v1
     [new_k2] => v2
     [new_k3] => v3
)

map

This method maps array values using the function. It invokes the function for each value in the array and creates a new array containing the values returned by the function.

Parameters: array $elements, $function

Example:

$array = ['k1', 'k2', 'k3'];
$result = Arrays::map($array, function ($value) {
    return 'new_' . $value;
});

Result:

Array
(
    [0] => new_k1
    [1] => new_k2
    [2] => new_k3
)

mapEntries

This method maps array values using the function which takes key and value as parameters. Invokes the function for each value in the array. Creates a new array containing the values returned by the function.

Parameters: array $elements, $function

Example:

$array = ['a' => '1', 'b' => '2', 'c' => '3'];
$result = Arrays::mapEntries($array, function ($key, $value) {
    return $key . '_' . $value;
});

Result:

Array
(
    [a] => a_1
    [b] => b_2
    [c] => c_3
)

filter

This method filters array using function. Result contains all elements for which function returns true Parameters: $elements, $function

Example:

$array = [1, 2, 3, 4];
$result = Arrays::filter($array, function ($value) {
    return $value > 2;
});

Result:

Array
(
    [2] => 3
    [3] => 4
)

filterNotBlank

Returns a new array without blank elements.

Parameters: array $elements


toArray

Makes an array from element. Returns the given argument if it’s already an array.

Parameters: $element

Example:

$result = Arrays::toArray('test');

Result:

Array
(
    [0] => test
)

randElement

Returns a random element from the given array.

Parameters: array $elements

Example:

$array = ['john', 'city', 'small'[;
$rand = Arrays::randElement($array);

Result: rand element from array


combine

Returns a new array with $keys as array keys and $values as array values.

Parameters: array $keys, array $values

Example:

$keys = ['id', 'name', 'surname'];
$values = [1, 'john', 'smith'];
$combined = Arrays::combine($keys, $values);

Result:

Array
(
    [id] => 1
    [name] => john
    [surname] => smith
)

keyExists

Checks is key exists in an array.

Parameters: array $elements, $key

Example:

$array = ['id' => 1, 'name' => 'john'];
$return = Arrays::keyExists($array, 'name');

Result: true


reduce

Method to reduce an array elements to a string value.

Parameters: array $elements, callable $function


find

Finds first element in array that is matched by function. Returns null if element was not found.

Parameters: array $elements, callable $function


intersect

Computes the intersection of arrays.

Parameters: array $array1, array $array2


setNestedValue

Sets nested value.

Parameters: array $array, array $keys, $value

Example:

$array = array();
Arrays::setNestedValue($array, array('1', '2', '3'), 'value');

Result:

Array
(
     [1] => Array
         (
             [2] => Array
                 (
                     [3] => value
                 )
         )
)

sort

Returns a new array sorted using given comparator. The comparator function must return an integer less than, equal to, or greater than zero if the first argument is considered to be respectively less than, equal to, or greater than the second. To obtain comparator one may use Comparator class (for instance Comparator::natural() which yields ordering using comparison operators).

Parameters: array $array, $comparator

Example:

class Foo
{
    private $value;

    public function __construct($value)
    {
      $this->value = $value;
    }

    public function getValue()
    {
      return $this->value;
    }
}
$values = [new Foo(1), new Foo(3), new Foo(2)];
$sorted = Arrays::sort($values, Comparator::compareBy('getValue()'));

Result:

Array
(
     [0] =>  class Foo (1) {
                 private $value => int(1)
             }
     [1] =>  class Foo (1) {
                 private $value => int(2)
             }
     [2] =>  class Foo (1) {
                 private $value => int(3)
             }
)

getNestedValue

Returns nested value when found, otherwise returns null.

Parameters: array $array, array $keys

Example:

$array = ['1' => ['2' => ['3' => 'value']]];
$value = Arrays::getNestedValue($array, ['1', '2', '3']);

Result: value


removeNestedValue

Deprecated since version 1.0.

Use Arrays::removeNestedKey instead.


removeNestedKey

Returns array with removed keys even are nested.

Parameters: array $array, array $keys

Example:

$array = ['1' => ['2' => ['3' => 'value']]];
Arrays::removeNestedKey($array, ['1', '2']);

Result:

Array
(
     [1] => Array
         (
         )
)

Note

It’s possible to remove keys when they don’t have any children using flag Arrays::REMOVE_EMPTY_PARENTS.

Example:

$array = ['1' => ['2' => ['3' => 'value']]];
Arrays::removeNestedKey($array, ['1', '2'], Arrays::REMOVE_EMPTY_PARENTS);

Result:

Array
(
)

hasNestedKey

Checks if array has a nested key.

Note

It’s possible to check array with null values using flag Arrays::TREAT_NULL_AS_VALUE.

Parameters: array $array, array $keys, $flags = null

Example:

$array = ['1' => ['2' => ['3' => 'value']]];
$value = Arrays::hasNestedKey($array, ['1', '2', '3']);

Result: true

Example with null values:

$array = ['1' => ['2' => ['3' => null]]];
$value = Arrays::hasNestedKey($array, ['1', '2', '3'], Arrays::TREAT_NULL_AS_VALUE);

Result: true


flattenKeysRecursively

Returns a flattened array of keys with corresponding values.

Parameters: array $array

Example:

$array = [
     'customer' => [
         'name' => 'Name',
         'phone' => '123456789'
     ],
     'other' => [
         'ids_map' => [
             '1qaz' => 'qaz',
             '2wsx' => 'wsx'
         ],
         'first' => [
             'second' => [
                 'third' => 'some value'
             ]
         ]
     ]
];
$flatten = Arrays::flattenKeysRecursively($array)

Result:

Array
(
     [customer.name] => Name
     [customer.phone] => 123456789
     [other.ids_map.1qaz] => qaz
     [other.ids_map.2wsx] => wsx
     [other.first.second.third] => some value
)

count

Returns the number of elements for which the predicate returns true.

Parameters: array $elements, $predicate

Example:

$array = [1, 2, 3];
$count = Arrays::count($array, function ($element) {
   return $element < 3;
});

Result: 2


uniqueBy

Removes duplicate values from an array. It uses the given expression to extract value that is compared.

Parameters: array $elements, $selector

Example:

$a = new stdClass();
$a->name = 'bob';

$b = new stdClass();
$b->name = 'bob';

$array = [$a, $b];
$result = Arrays::uniqueBy($array, 'name');

Result:

Array
(
    [0] => $b
)

recursiveDiff

Returns a recursive diff of two arrays

Parameters: array $array1, array $array2

Example:

$array1 = array('a' => array('b' => 'c', 'd' => 'e'), 'f');
$array2 = array('a' => array('b' => 'c'));
$result = Arrays::recursiveDiff($array1, $array2);

Result:

Array
(
 [a] => Array
       (
         [d] => e
       )
 [0] => f
)