PHP Class Ouzo\Utilities\Arrays

Show file Open project: letsdrink/ouzo Class Usage Examples

Public Methods

Method	Description
all ( array $elements, callable $predicate ) : boolean	Returns true if every element in array satisfies the predicate.
any ( array $elements, callable $predicate ) : boolean	Returns true if at least one element in the array satisfies the predicate.
combine ( array $keys, array $values ) : array	Returns a new array with $keys as array keys and $values as array values.
concat ( array $arrays ) : array	Merges array of arrays into one array.
contains ( array $array, mixed $element ) : boolean	Returns true if array contains given element. Comparison is based on the following rules: - same type + same type = strict check - object + object = loose check - array + array = goes through all elements and invokes Arrays::contains - string + integer = loose check - boolean + string ('true' or 'false') = loose check - false in other cases Example: `$result = Arrays::contains(array(1, 2, 3), 2);` Result: `true`
count ( array $elements, callable $predicate ) : integer	Returns the number of elements for which the predicate returns true.
filter ( array $elements, callable $function ) : array	This method filters array using function. Result contains all elements for which function returns true.
filterByAllowedKeys ( array $elements, array $allowedKeys ) : array	Returns an array containing only the given keys.
filterByKeys ( array $elements, callable $predicate ) : array	Filters array by keys using the predicate.
filterNotBlank ( array $elements ) : array	This method filter array will remove all values that are blank.
find ( array $elements, callable $function ) : mixed	Finds first element in array that is matched by function.
findKeyByValue ( array $elements, string $value ) : boolean \| integer \| string	This method returns a key for the given value.
first ( array $elements ) : mixed	This method returns the first value in the given array.
firstOrNull ( array $elements ) : mixed \| null	This method returns the first value or null if array is empty.
flatten ( array $array ) : array	Returns a new array that is a one-dimensional flattening of the given array.
flattenKeysRecursively ( array $array ) : array	Returns maps of the flatten keys with corresponding values.
getNestedValue ( array $array, array $keys ) : array \| mixed \| null	Return nested value when found, otherwise return null value.
getValue ( array $elements, string \| integer $key, mixed \| null $default = null ) : mixed \| null	Returns the element for the given key or a default value otherwise.
groupBy ( array $elements, callable $keyFunction, string \| null $orderField = null ) : array	Group elements in array by result of the given function. If $orderField is set grouped elements will be also sorted.
hasNestedKey ( array $array, array $keys, null $flags = null ) : boolean	Checks if array has nested key. It's possible to check array with null values using flag Arrays::TREAT_NULL_AS_VALUE.
intersect ( array $array1, array $array2 ) : array	Computes the intersection of arrays.
isAssociative ( array $array ) : boolean	Checks if the given array is associative. An array is considered associative when it has at least one string key.
keyExists ( array $elements, string \| integer $key ) : boolean	Checks is key exists in an array.
last ( array $elements ) : mixed	This method returns the last value in the given array.
map ( array $elements, callable $function ) : array	This method maps array values using the function.
mapEntries ( array $elements, callable $function ) : array	This method maps array values using the function which takes key and value as parameters.
mapKeys ( array $elements, callable $function ) : array	This method maps array keys using the function.
orderBy ( array $elements, string $orderField ) : array	This method sorts elements in array using order field.
randElement ( array $elements ) : null	Returns a random element from the given array.
recursiveDiff ( array $array1, array $array2 ) : array	Returns a recursive diff of two arrays 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'), 'f')`
reduce ( array $elements, callable $function ) : mixed	Method to reduce an array elements to a string value.
removeNestedKey ( array &$array, array $keys, boolean $removeEmptyParents = false )	Removes nested keys in array.
removeNestedValue ( array &$array, array $keys )
setNestedValue ( array &$array, array $keys, $value )	Setting nested value.
shuffle ( array $array ) : array	Returns shuffled array with retained key association.
sort ( array $array, $comparator ) : array	Returns a new array with is sorted using given comparator.
toArray ( mixed $element ) : array	Make array from element. Returns the given argument if it's already an array.
toMap ( array $elements, callable $keyFunction, callable \| null $valueFunction = null ) : array	This method creates associative array using key and value functions on array elements.
uniqueBy ( array $elements, $selector ) : array	Removes duplicate values from an array. It uses the given expression to extract value that is compared.

Private Methods

Method	Description
_flattenKeyRecursively ( $array, &$result, $parentKey )

Method Details

all() public static method

Example:


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

Result:


true

public static all ( array $elements, callable $predicate ) : boolean
$elements	array
$predicate	callable
return	boolean

any() public static method

Example:


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

Result:


true

public static any ( array $elements, callable $predicate ) : boolean
$elements	array
$predicate	callable
return	boolean

combine() public static method

Example:


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

Result:


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

public static combine ( array $keys, array $values ) : array
$keys	array
$values	array
return	array

concat() public static method

Unlike flatten, concat does not merge arrays that are nested more that once. Example:


$result = Arrays::concat(array(array(1, 2), array(3, 4)));

Result:


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

public static concat ( array $arrays ) : array
$arrays	array
return	array

contains() public static method

Returns true if array contains given element. Comparison is based on the following rules: - same type + same type = strict check - object + object = loose check - array + array = goes through all elements and invokes Arrays::contains - string + integer = loose check - boolean + string ('true' or 'false') = loose check - false in other cases Example:


$result = Arrays::contains(array(1, 2, 3), 2);

Result:


true

public static contains ( array $array, mixed $element ) : boolean
$array	array
$element	mixed	expected value
return	boolean

count() public static method

Example:


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

Result:

public static count ( array $elements, callable $predicate ) : integer
$elements	array
$predicate	callable
return	integer

filter() public static method

Example:


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

Result:


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

public static filter ( array $elements, callable $function ) : array
$elements	array
$function	callable
return	array

filterByAllowedKeys() public static method

Example:


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

Result:


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

public static filterByAllowedKeys ( array $elements, array $allowedKeys ) : array
$elements	array
$allowedKeys	array
return	array

filterByKeys() public static method

Example:


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

Result:


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

public static filterByKeys ( array $elements, callable $predicate ) : array
$elements	array
$predicate	callable
return	array

filterNotBlank() public static method

This method filter array will remove all values that are blank.

public static filterNotBlank ( array $elements ) : array
$elements	array
return	array

find() public static method

Returns null if element was not found.

public static find ( array $elements, callable $function ) : mixed
$elements	array
$function	callable
return	mixed

findKeyByValue() public static method

Example:


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

Result:

k3

public static findKeyByValue ( array $elements, string $value ) : boolean \| integer \| string
$elements	array
$value	string
return	boolean \| integer \| string

first() public static method

Example:


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

Result: one

public static first ( array $elements ) : mixed
$elements	array
return	mixed

firstOrNull() public static method

Example:


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

Result: null

public static firstOrNull ( array $elements ) : mixed \| null
$elements	array
return	mixed \| null

flatten() public static method

Example:


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

Result:


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

public static flatten ( array $array ) : array
$array	array
return	array

flattenKeysRecursively() public static method

Example:


$array = array(
     'customer' => array(
         'name' => 'Name',
         'phone' => '123456789'
     ),
     'other' => array(
         'ids_map' => array(
             '1qaz' => 'qaz',
             '2wsx' => 'wsx'
         ),
         'first' => array(
             'second' => array(
                 '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
)

public static flattenKeysRecursively ( array $array ) : array
$array	array
return	array

getNestedValue() public static method

Example:


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

Result:


value

public static getNestedValue ( array $array, array $keys ) : array \| mixed \| null
$array	array
$keys	array
return	array \| mixed \| null

getValue() public static method

Example:


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

Result: john Example:


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

Result: --not found--

public static getValue ( array $elements, string \| integer $key, mixed \| null $default = null ) : mixed \| null
$elements	array
$key	string \| integer
$default	mixed \| null
return	mixed \| null

groupBy() public static method

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 = 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
         )
     )
)

public static groupBy ( array $elements, callable $keyFunction, string \| null $orderField = null ) : array
$elements	array
$keyFunction	callable
$orderField	string \| null
return	array

hasNestedKey() public static method

Example:


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

Result:


true

Example with null values:


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

Result:


true

public static hasNestedKey ( array $array, array $keys, null $flags = null ) : boolean
$array	array
$keys	array
$flags	null
return	boolean

intersect() public static method

Computes the intersection of arrays.

public static intersect ( array $array1, array $array2 ) : array
$array1	array
$array2	array
return	array

isAssociative() public static method

Example:


$result = Arrays::isAssociative(array(1, '2', 'abc'));

Result:


FALSE


$result = Arrays::isAssociative(array(1 => 'b', 'a' => 2, 'abc'));

Result:


TRUE

public static isAssociative ( array $array ) : boolean
$array	array
return	boolean

keyExists() public static method

Example:


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

Result: true

public static keyExists ( array $elements, string \| integer $key ) : boolean
$elements	array
$key	string \| integer
return	boolean

last() public static method

Example:


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

Result: c

public static last ( array $elements ) : mixed
$elements	array
return	mixed

map() public static method

Invokes the function for each value in the array. Creates a new array containing the values returned by the function. Example:


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

Result:


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

public static map ( array $elements, callable $function ) : array
$elements	array
$function	callable
return	array

mapEntries() public static method

Invokes the function for each value in the array. Creates a new array containing the values returned by the function. Example:


$array = 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
)

public static mapEntries ( array $elements, callable $function ) : array
$elements	array
$function	callable
return	array

mapKeys() public static method

Invokes the function for each key in the array. Creates a new array containing the keys returned by the function. Example:


$array = 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
)

public static mapKeys ( array $elements, callable $function ) : array
$elements	array
$function	callable
return	array

orderBy() public static method

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 = 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
     )
)

public static orderBy ( array $elements, string $orderField ) : array
$elements	array
$orderField	string
return	array

randElement() public static method

Example:


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

Result: rand element from array

public static randElement ( array $elements ) : null
$elements	array
return	null

recursiveDiff() public static method

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

public static recursiveDiff ( array $array1, array $array2 ) : array
$array1	array
$array2	array
return	array

reduce() public static method

Method to reduce an array elements to a string value.

public static reduce ( array $elements, callable $function ) : mixed
$elements	array
$function	callable
return	mixed

removeNestedKey() public static method

Example:


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

Result:


Array
(
     [1] => Array
         (
         )
)

public static removeNestedKey ( array &$array, array $keys, boolean $removeEmptyParents = false )
$array	array
$keys	array
$removeEmptyParents	boolean

removeNestedValue() public static method

Deprecation:

public static removeNestedValue ( array &$array, array $keys )
$array	array
$keys	array

setNestedValue() public static method

Example:


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

Result:


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

public static setNestedValue ( array &$array, array $keys, $value )
$array	array
$keys	array
$value

shuffle() public static method

Example:


$result = Arrays::shuffle(array(1 => 'a', 2 => 'b', 3 => 'c'));

Result:


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

public static shuffle ( array $array ) : array
$array	array
return	array

sort() public static method

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). Example:


class Foo
{
     private $value;
     function __construct($value)
     {
         $this->value = $value;
     }
     public function getValue()
     {
         return $this->value;
     }
}
$values = array(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)
             }
)

public static sort ( array $array, $comparator ) : array
$array	array
$comparator
return	array	sorted according to the comparator

toArray() public static method

Example:


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

Result:


Array
(
     [0] => test
)

public static toArray ( mixed $element ) : array
$element	mixed
return	array

toMap() public static method

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
)

public static toMap ( array $elements, callable $keyFunction, callable \| null $valueFunction = null ) : array
$elements	array
$keyFunction	callable
$valueFunction	callable \| null
return	array

uniqueBy() public static method

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
)

public static uniqueBy ( array $elements, $selector ) : array
$elements	array
$selector
return	array