Arr Class
The arr class is a set of helper functions for working with arrays.
is_multi($arr, $all_keys = false)
The is_multi method checks if the array passed is multi-dimensional array or not.
Static |
Yes |
Parameters |
Param |
Default |
Description |
$arr |
required |
The array to check. |
$all_keys |
false
|
Check that all elements are arrays. |
|
Returns |
bool |
Example |
// Single array
$arr = array('one' => 1, 'two' => 2);
echo Arr::is_multi($arr);
// Result: false
// Multi-dimensional array
$arr = array('one' => array('test' => 1), 'two' => array('test' => 2), 'three' => array('test' => 3));
echo Arr::is_multi($arr);
// Result: true
// Multi-dimensional array with elements check
$arr = array('one' => array('test' => 1), 'two' => array('test' => 2), 'three' => 3);
echo Arr::is_multi($arr, false); // Result: true
echo Arr::is_multi($arr, true); // Result: false
|
is_assoc($arr)
The is_assoc method checks if the array passed is an associative array or not.
Static |
Yes |
Parameters |
Param |
Default |
Description |
$arr |
required |
The array to check. |
|
Returns |
bool |
Example |
$arr = array('foo', 'bar', 'baz', 'yay');
echo Arr::is_assoc($arr);
// Result: false
$arr = array('foo' => 'foo', 'bar' => 'bar', 'baz' => 'baz', 'yay' => 'yay');
echo Arr::is_assoc($arr);
// Result: true
/*
* Note that even if the '2' is defined as a string, PHP will store this internally
* as an integer, and therefore this is NOT seen as an assoc array!
*/
$arr = array(0 => 'foo', 1 => 'bar', '2' => 'baz', 3 => 'yay');
echo Arr::is_assoc($arr);
// Result: false!
|
to_assoc($arr)
The to_assoc method turns a non-associative array into an associative array if it has an even number of segments.
Static |
Yes |
Parameters |
Param |
Default |
Description |
$arr |
required |
The array to convert. |
|
Returns |
array|null |
Throws |
BadMethodCallException when the number of values in the given array is
uneven |
Example |
$arr = array('foo', 'bar', 'baz', 'yay');
print_r(Arr::to_assoc($arr));
// Result:
Array
(
["foo"] => 'bar'
["baz"] => 'yay'
)
$arr = array('foo', 'bar', 'baz');
echo Arr::to_assoc($arr);
// Result: null
|
assoc_to_keyval($assoc = null, $key_field = null, $val_field = null)
The assoc_to_keyval method turns a multi-dimensional array into a key=>val array.
Static |
Yes |
Parameters |
Param |
Default |
Description |
$assoc |
required |
The array to transform. |
$key_field |
required |
The associative array field to map as the key. |
$val_field |
required |
The associative array field to map as the value. |
|
Returns |
array |
Throws |
InvalidArgumentException when the first argument isn't an array or doesn't
implement the Iterator interface. |
Example |
$people = array(
array(
"name" => "Jack",
"age" => 21
),
array(
"name" => "Jill",
"age" => 23
)
);
print_r(Arr::assoc_to_keyval($people, 'name', 'age'));
// Result:
Array
(
["Jack"] => 21
["Jill"] => 23
)
|
average($array = null)
The average method takes all values of an array and returns the average value.
Static |
Yes |
Parameters |
Param |
Default |
Description |
$array |
required |
Array of values to average. |
|
Returns |
array |
Example |
echo Arr::average(array('1', 2, 4, '8'));
// Result: 3.75
|
flatten($array, $glue = ':', $reset = true)
The flatten method flattens a multi-dimensional array (both associative and indexed) down into a 1 dimensional array.
Static |
Yes |
Parameters |
Param |
Default |
Description |
$array |
required |
The array to flatten. |
$glue |
:
|
The string used to glue the keys together with |
$reset |
true
|
Should we create a new array of values instead of merging them into the last array created by flatten? |
|
Returns |
array |
Example |
$indexed = array(
array("a"),
array("b"),
array("c"),
);
print_r(Arr::flatten($indexed, '_'));
// Result:
Array
(
[0_0] => a
[0_1] => b
[0_2] => c
)
|
flatten_assoc($array, $glue = ':', $reset = true)
The flatten_assoc method flattens a multi-dimensional associative array down into a 1 dimensional associative array.
Static |
Yes |
Parameters |
Param |
Default |
Description |
$array |
required |
The array to flatten. |
$glue |
:
|
The string used to glue the keys together with |
$reset |
true
|
Should we create a new array of values instead of merging them into the last array created by flatten_assoc? |
|
Returns |
array |
Example |
$people = array(
array(
"name" => "Jack",
"age" => 21
),
array(
"name" => "Jill",
"age" => 23
)
);
print_r(Arr::flatten_assoc($people));
// Result:
Array
(
[0:name] => Jack
[0:age] => 21
[1:name] => Jill
[1:age] => 23
)
// Let's flatten another array on top
print_r(Arr::flatten_assoc(array(array("name" => "Humpty", "age" => 11)), ":", false));
// Result:
Array
(
[0:name] => Humpty
[0:age] => 11
[1:name] => Jill
[1:age] => 23
)
|
reverse_flatten($array, $glue = ':')
The reverse_flatten method unflattens a flattened multi-dimensional array (both associative and indexed) into its original form.
Static |
Yes |
Parameters |
Param |
Default |
Description |
$array |
required |
The array to unflatten. |
$glue |
:
|
The string used to glue the keys together with |
|
Returns |
array |
Example |
$flattened = array(
'0_name' => 'James',
'0_age' => 24,
'1_name' => 'John',
'1_age' => 34,
);
print_r(Arr::reverse_flatten($flattened, '_'));
// Result:
Array
(
[0] => Array
(
[name] => James
[age] => 24
)
[1] => Array
(
[name] => John
[age] => 34
)
)
|
filter_prefixed($array, $prefix, $remove_prefix = true)
The filter_prefixed method filters the array on a prefix. It returns an array where the key starts with the specified prefix.
Static |
Yes |
Parameters |
Param |
Default |
Description |
$array |
required |
The array to filter. |
$prefix |
required |
The string used to filter on |
$remove_prefix |
true
|
Remove or keep the prefix in the array key? |
|
Returns |
array |
Example |
$arr = array(
"user_name" => "John",
"user_surname" => "Lastname",
"project_name" => "Fuel",
"project_type" => "Framework",
);
print_r(Arr::filter_prefixed($arr, "user_"));
// Result:
Array
(
[name] => John
[surname] => Lastname
)
// Let's keep the prefix
print_r(Arr::filter_prefixed($arr, "project_", false);
// Result:
Array
(
[project_name] => Fuel
[project_type] => Framework
)
|
remove_prefixed($array, $prefix)
The remove_prefixed method removes values from an array if they match a given prefix.
Static |
Yes |
Parameters |
Param |
Default |
Description |
$array |
required |
The array to remove from. |
$prefix |
required |
The string used to filter on |
|
Returns |
array |
Example |
$arr = array(
"user_name" => "John",
"user_surname" => "Lastname",
"project_name" => "Fuel",
"project_type" => "Framework",
);
print_r(Arr::remove_prefixed($arr, "project"));
// Result:
Array
(
[user_name] => John
[user_surname] => Lastname
)
|
filter_suffixed($array, $suffix, $remove_suffix = true)
The filter_suffixed method filters the array on a suffix. It returns an array where the key ends with the specified suffix.
Static |
Yes |
Parameters |
Param |
Default |
Description |
$array |
required |
The array to filter. |
$suffix |
required |
The string used to filter on |
$remove_suffix |
true
|
Remove or keep the suffix in the array key? |
|
Returns |
array |
Example |
$arr = array(
"name_1" => "John",
"surname_1" => "Lastname",
"name_2" => "Ted",
"surname_2" => "Surname",
);
print_r(Arr::filter_suffixed($arr, "_1"));
// Result:
Array
(
[name] => John
[surname] => Lastname
)
// Let's keep the suffix
print_r(Arr::filter_suffixed($arr, "_1", false);
// Result:
Array
(
[name_1] => John
[surname_1] => Lastname
)
|
remove_suffixed($array, $suffix)
The remove_suffixed method removes values from an array if they match a given suffix.
Static |
Yes |
Parameters |
Param |
Default |
Description |
$array |
required |
The array to remove from. |
$suffix |
required |
The string used to filter on |
|
Returns |
array |
Example |
$arr = array(
"name_1" => "John",
"surname_1" => "Lastname",
"name_2" => "Ted",
"surname_2" => "Bear",
);
print_r(Arr::remove_suffixed($arr, "_1"));
// Result:
Array
(
[name_2] => Ted
[surname_2] => Surname
)
|
filter_keys($array, $keys, $remove = false)
The filter_keys method filters a given array to a set of keys. It returns an array that contains only the items whose keys are in the $keys array. Can also remove the specified $keys from an array.
Static |
Yes |
Parameters |
Param |
Default |
Description |
$array |
required |
The array to filter. |
$keys |
required |
Array of keys to filter the above array with. |
$remove |
false
|
If true, removes the $keys from the $array instead of fetching them. |
|
Returns |
array |
Example |
$arr = array(
"user_name" => "John",
"user_surname" => "Lastname",
"project_name" => "Fuel",
"project_type" => "Framework",
);
print_r(Arr::filter_keys($arr, array('project_name', 'user_name')));
// Result:
Array
(
[project_name] => Fuel
[user_name] => John
)
// Let's remove some keys
print_r(Arr::filter_keys($arr, array('user_name', 'user_surname'), true));
// Result:
Array
(
[project_name] => Fuel
[project_type] => Framework
)
|
filter_recursive($array, $callback = null)
The filter_recursive method provides a recursive version of PHP's array_filter() function. Like it's counterpart, you can optionally pass a callback function to determine what should be filtered.
Static |
Yes |
Parameters |
Param |
Default |
Description |
$array |
required |
The array to filter. |
$callback |
null
|
A valid callback that returns a boolean. |
|
Returns |
array |
Example |
$arr = array(
"user_name" => "John",
"user_surname" => "Lastname",
"info" => array(
0 => array(
"data" = "a value",
),
1 => array(
"data" = "",
),
2 => array(
"data" = 0,
),
),
);
print_r(Arr::filter_recursive($arr));
// Result:
Array
(
[project_name] => Fuel
[user_name] => John
[info] => Array
(
[0] => Array
(
[data] => a value
)
)
)
// Let's use a callback
print_r(Arr::filter_recursive($arr, function($item){ return $item !== ""; });
// Result:
Array
(
[project_name] => Fuel
[user_name] => John
[info] => Array
(
[0] => Array
(
[data] => a value
)
[2] => Array
(
[data] => 0
)
)
)
|
get($array, $key, $default = false)
The get method returns the element of the given array using dot-notation, or a default if it is not set.
Static |
Yes |
Parameters |
Param |
Default |
Description |
$array |
required |
The array to access |
$key |
required |
The key requested in $array. If null is passed as key, the entire array is returned. |
$default |
false
|
The value to be returned if the requested key does not exist |
|
Returns |
mixed. If you pass an array of keys, the return value will be an array with the result of all requested keys. |
Example |
$person = array(
"name" => "Jack",
"age" => "21",
"location" => array(
"city" => "Pittsburgh",
"state" => "PA",
"country" => "US"
)
);
echo Arr::get($person, "name", "Unknown Name");
// Result: "Jack"
echo Arr::get($person, "job", "Unknown job");
// Result: "Unknown job"
// This method can also dive into arrays by using a dot to separate between keys
echo Arr::get($person, "location.city", "Unknown City");
// Result: "Pittsburgh"
|
set(&$array, $key, $value = null)
The set method sets the element of the given array using dot-notation.
WARNING: The original array is edited by reference
Static |
Yes |
Parameters |
Param |
Default |
Description |
$array |
required |
The array to access |
$key |
required |
The key requested in $array. If no key is passed, or null is passed as key value, the array is unset. If you pass an array of key -> value pairs, all the values in the array will be set. |
$value |
null
|
The value to be set. Ignored if $key is an array. |
|
Returns |
void |
Example |
$person = array(
"name" => "Jack",
"age" => "21",
"location" => array(
"city" => "Pittsburgh",
"state" => "PA",
"country" => "US"
)
);
Arr::set($person, "name", "John");
// $person['name'] is set to "John"
// This method can also dive into arrays by using a dot to separate between keys
Arr::set($person, "location.city", "Philadelphia");
// $person['location']['city'] is set to "Philadelphia"
// or set multiple values in one go
Arr::set($person, array("name" => "John", "location.city" => "Philadelphia"));
|
pluck($array, $key, $index = null)
The pluck method plucks values from a collection of arrays or objects.
Static |
Yes |
Parameters |
Param |
Default |
Description |
$array |
required |
The array to pluck from |
$key |
required |
The key to pluck from the arrays. |
$index |
null
|
Optional return array index. |
|
Returns |
void |
Example |
$collection = array(
array(
'id' => 2,
'name' => 'Bill',
'surname' => 'Cosby',
),
array(
'id' => 5,
'name' => 'Chris',
'surname' => 'Rock',
),
array(
'id' => 7,
'name' => 'Bert',
'surname' => 'Visser',
),
);
// Get an array of id's
$ids = \Arr::pluck($collection, 'id');
// array(2, 5, 7);
// Get an array of names with the id as the index
$names = \Arr::pluck($collection, 'name', 'id');
// array(2 => 'Bill', 5 => 'Chris', 7 => 'Bert');
|
delete(&$array, $key)
The delete method the element of the given array using dot-notation.
WARNING: The original array is edited by reference, only boolean success is returned
Static |
Yes |
Parameters |
Param |
Default |
Description |
$array |
required |
The array to access |
$key |
required |
The key requested in $array. If no key is passed, or null is passed as key value, the array is unset. |
|
Returns |
mixed, true if the key was deleted, false if the key didn't exist. If you pass an array of keys, the return value will be an array with the result of all requested deletes. |
Example |
$person = array(
"name" => "Jack",
"age" => "21",
"location" => array(
"city" => "Pittsburgh",
"state" => "PA",
"country" => "US"
)
);
$result = Arr::delete($person, "name");
// deleted $person['name'] from the array, returns true
// This method can also dive into arrays by using a dot to separate between keys
$result = Arr::delete($person, "location.city");
// deleted $person['location']['city'] from the array, returns true
// or delete multiple values in one go
$result = Arr::delete($person, array("name", "location.doesnotexist"));
// deleted $person['name'], returns array('name' => true, 'location.doesnotexist' => false)
|
insert(Array &$original, $value, $pos)
The insert method is mainly an array_splice alias with added error checking
WARNING: The original array is edited by reference, only boolean success is returned
Static |
Yes |
Parameters |
Param |
Default |
Description |
$original |
required |
The array to use |
$value |
required |
The value(s) to insert |
$pos |
required |
The numeric position at which to insert, negative to count from the end backwards |
|
Returns |
boolean |
Example |
$people = array("Jack", "Jill");
// Add one value
Arr::insert($people, "Humpty", 0);
print_r($people);
// Result:
Array
(
[0] => Humpty
[1] => Jack
[2] => Jill
)
// Add multiple values
Arr::insert($people, array("Hansel", "Gretel"), 1);
print_r($people);
// Result:
Array
(
[0] => Humpty
[1] => Hansel
[2] => Gretel
[3] => Jack
[4] => Jill
)
// Add an array
Arr::insert($people, array( array("name" => "Wolf", "teeth" => "sharp")), 0);
print_r($people);
// Result:
Array
(
[0] => Array
(
[name] => Wolf
[teeth] => sharp
)
[1] => Humpty
[2] => Hansel
[3] => Gretel
[4] => Jack
[5] => Jill
)
|
insert_before_key(Array &$original, $value, $key)
The insert_before_key method adds an element to an array before the key specified
WARNING: The original array is edited by reference, only boolean success is returned
Static |
Yes |
Parameters |
Param |
Default |
Description |
$original |
required |
The array to use |
$value |
required |
The value(s) to insert |
$key |
required |
The key before which to insert |
|
Returns |
boolean |
Example |
$people = array("Jack", "Jill");
Arr::insert_before_key($people, "Humpty", 1);
print_r($people);
// Result:
Array
(
[0] => Jack
[1] => Humpty
[2] => Jill
)
|
insert_after_key(Array &$original, $value, $key, $is_assoc = false)
The insert_after_key method adds an element to an array after the key specified
WARNING: The original array is edited by reference, only boolean success is returned
Static |
Yes |
Parameters |
Param |
Default |
Description |
$original |
required |
The array to use |
$value |
required |
The value(s) to insert |
$key |
required |
The key after which to insert |
$is_assoc |
false
|
Whether the array is assoc |
|
Returns |
boolean |
Example |
$people = array("Jack", "Jill");
Arr::insert_after_key($people, "Humpty", 1);
print_r($people);
// Result:
Array
(
[0] => Jack
[1] => Jill
[2] => Humpty
)
|
insert_after_value(Array &$original, $value, $search, $is_assoc = false)
The insert_after_value method adds an element to an array after the value specified
WARNING: The original array is edited by reference, only boolean success is returned
Static |
Yes |
Parameters |
Param |
Default |
Description |
$original |
required |
The array to use |
$value |
required |
The value(s) to insert |
$search |
required |
The value after which to insert |
$is_assoc |
false
|
Whether the array is assoc |
|
Returns |
boolean |
Example |
$people = array("Jack", "Jill");
Arr::insert_after_value($people, "Humpty", "Jack");
print_r($people);
// Result:
Array
(
[0] => Jack
[1] => Humpty
[2] => Jill
)
|
sort($array, $key, $order = 'asc', $sort_flags = SORT_REGULAR)
The sort method sorts a multi-dimensional array by its values.
Static |
Yes |
Parameters |
Param |
Default |
Description |
$array |
required |
The array to sort |
$key |
required |
The key requested to sort by in $array. |
$order |
'asc'
|
The order (asc or desc). |
$sort_flags |
SORT_REGULAR
|
The php sort type flags (http://php.net/manual/en/function.sort.php) |
|
Returns |
mixed |
Example |
$data = array(
array(
'info' => array(
'pet' => array(
'type' => 'dog'
)
),
),
array(
'info' => array(
'pet' => array(
'type' => 'fish'
)
),
),
array(
'info' => array(
'pet' => array(
'type' => 'cat'
)
),
),
);
$data = Arr::sort($data, 'info.pet.type');
// Result:
array(
array(
'info' => array(
'pet' => array(
'type' => 'cat'
)
),
),
array(
'info' => array(
'pet' => array(
'type' => 'dog'
)
),
),
array(
'info' => array(
'pet' => array(
'type' => 'fish'
)
),
),
);
|
multisort($array, $conditions, $ignore_case = false)
The sort method sorts a multi-dimensional array by multiple values.
Static |
Yes |
Parameters |
Param |
Default |
Description |
$array |
required |
The array to sort |
$conditions |
required |
Array of sorting conditions. |
$ornire_case |
false
|
Wether to sort case insensitive. |
|
Returns |
array |
Example |
$collection = array(
'i5' => array(
'name' => 'Carl',
'age' => 17,
'points' => 30,
'arr' => array(
'key' => 10,
),
),
'i7' => array(
'name' => 'carl',
'age' => 17,
'points' => 20,
'arr' => array(
'key' => 10,
),
),
'i2' => array(
'name' => 'Bert',
'age' => 20,
'points' => 30,
'arr' => array(
'key' => 10,
),
),
);
$collection = \Arr::multisort($collection, array(
'name' => SORT_ASC,
'points' => array(SORT_ASC, SORT_NUMERIC),
'age' => array(SORT_ASC, SORT_NUMERIC),
), true);
print_r($collection);
// Result
Array
(
[i2] => Array
(
[name] => Bert
[age] => 20
[points] => 30
[arr] => Array
(
[key] => 10
)
)
[i7] => Array
(
[name] => carl
[age] => 17
[points] => 20
[arr] => Array
(
[key] => 10
)
)
[i5] => Array
(
[name] => Carl
[age] => 17
[points] => 30
[arr] => Array
(
[key] => 10
)
)
)
|
in_array_recursive($needle, $haystack, $strict = false)
The in_array_recursive method checks wether a value is in an array recursively.
Static |
Yes |
Parameters |
Param |
Default |
Description |
$needle |
required |
The value to search for |
$haystack |
required |
The array to search in. |
$strict |
false
|
The wether to use == or ===. |
|
Returns |
bool |
Example |
$arr = array('one' => 1, 2, 3, array(56), 87);
echo Arr::in_array_recursive('56', $arr);
// Result: true
echo Arr::in_array_recursive('87', $arr, true);
// Result: false
echo Arr::in_array_recursive(87, $arr, true);
// Result: true
|
merge($array)
The merge method merges 2 arrays recursively, differs in 2 important ways from array_merge_recursive():
- When there's 2 different values and not both arrays, the latter value overwrites the earlier
instead of merging both into an array
- Numeric keys that don't conflict aren't changed, only when a numeric key already exists is the
value added using array_push()
Static |
Yes |
Parameters |
Param |
Type |
Default |
Description |
$array |
array |
required |
Multiple variables all of which must be arrays |
|
Returns |
array |
Throws |
InvalidArgumentException when one of the passed arguments is no array. |
Example |
$arr1 = array(
'one' => 1,
2,
3,
array(
56
),
87
);
$arr2 = array(
27,
90,
array(
'give_me' => 'bandwidth'
),
'90',
'php',
);
print_r( Arr::merge($arr1, $arr2) );
// Result:
Array
(
[one] => 1
[0] => 2
[1] => 3
[2] => Array (
[0] => 56
)
[3] => 87
[4] => 27
[5] => 90
[6] => Array (
[give_me] => bandwidth
)
[7] => 90
[8] => php
)
|
search($array, $value, $default = null, $recursive = true, $delimiter = '.')
The search method searches the array for a given value and returns the corresponding key or default value.
- If $recursive is set to true, then the search method will return a delimiter-notated key using $delimiter.
Static |
Yes |
Parameters |
Param |
Type |
Default |
Description |
$array |
array |
required |
The array to search |
$value |
mixed |
required |
The searched value |
$default |
string |
null
|
The key to be returned if the requested value does not exist |
$recursive |
boolean |
true
|
Whether to get keys recursively |
$delimiter |
string |
'.'
|
The delimiter when $recursive is true |
|
Returns |
int|string|null |
Throws |
InvalidArgumentException when first argument is not array.
InvalidArgumentException $default argument is not string or int or null.
InvalidArgumentException $delimiter argument is not string.
|
Example |
$arr = array(
'one' => 1,
'two' => 2,
'three' => array(
'a' => 4,
'b' => 'foo'
),
'four',
array(
null,
array(
null,
null,
null,
array(
'deep'
)
)
),
);
);
echo Arr::search($arr, 1);
// one
echo Arr::search($arr, 'four');
// 0
var_dump(Arr::search($arr, 5));
// NULL
echo Arr::search($arr, 4, null, true);
// three.a
echo Arr::search($arr, 'deep', null, true);
// 1.1.3.0
|
unique($array)
The unique returns an array with all unique values in the source array.
The first value matched will be kept, duplicates will be discarded. Keys will be preserved.
This method works like array_unique(), but doesn't sort the array first, and
allows you to dedup arrays that contain objects or closures.
Parameters |
Param |
Type |
Default |
Description |
$array |
array |
required |
the array to de-duplicate |
|
Returns |
array |
Example |
$array = array(
'val1' => 'test', 'val2' => 'test', 'val1' => 'dup',
);
// Result: array('val1' => 'test', 'val2' => 'test')
$result = Arr::unique($array);
|
sum($array, $key)
The sum method calculate the sum of values in an array plucked by the $key.
Static |
Yes |
Parameters |
Param |
Type |
Default |
Description |
$array |
array |
required |
the array containing the values |
$key |
string |
required |
The key to pluck from the arrays |
|
Returns |
int |
Throws |
InvalidArgumentException when one of the passed arguments is no array. |
Example |
$collection = array(
array(
'age' => 20,
'name' => 'Bill',
'scores' => array(
'math' => 10,
),
),
array(
'age' => 25,
'name' => 'Chris',
'scores' => array(
'math' => 15,
),
),
array(
'age' => 38,
'name' => 'Bert',
'scores' => array(
'math' => 5,
),
),
);
// Calculate sum of an array of age's
$total_age = Arr::sum($collection, 'age'); // 83
// Calculate sum of an array plucked by 'scores.math'
$total_score = Arr::sum($collection, 'scores.math'); // 30
|
Procedural helpers
in_arrayi($needle, $haystack)
The in_arrayi function is a case-insensitive version of in_array.
Parameters |
Param |
Type |
Default |
Description |
$needle |
string |
required |
the value to search for |
$haystrack |
array |
required |
the array to search in |
|
Returns |
bool |
Example |
echo in_arrayi('This', array('something','tHis'));
// Result: true
echo in_arrayi('Thi', array('something','tHis'));
// Result: false
|