Array helper.
Class declared in SYSPATH/classes/arr.php on line 3.
string $delimiterlink to thisdefault delimiter for path()
string(1) "."Creates a callable function and parameter list from a string representation. Note that this function does not validate the callback string.
// Get the callback function and parameterslist($func,$params) = Arr::callback('Foo::bar(apple,orange)');// Get the result of the callback$result= call_user_func_array($func,$params);
string
$str
required - Callback stringarray - Function, params
publicstaticfunctioncallback($str){// Overloaded as parts are found$command=$params= NULL;// command[param,param]if(preg_match('/^([^\(]*+)\((.*)\)$/',$str,$match)){// command$command=$match[1];if($match[2] !==''){// param,param$params= preg_split('/(?<!\\\\),/',$match[2]);$params=str_replace('\,',',',$params);}}else{// command$command=$str;}if(strpos($command,'::') !== FALSE){// Create a static method callable command$command=explode('::',$command, 2);}returnarray($command,$params);}
Retrieves multiple keys from an array. If the key does not exist in the array, the default value will be added instead.
// Get the values "username", "password" from $_POST$auth= Arr::extract($_POST,array('username','password'));
array
$array
required - Array to extract keys fromarray
$keys
required - List of key namesmixed
$default
= NULL - Default valuearray
publicstaticfunctionextract($array,array$keys,$default= NULL){$found=array();foreach($keysas$key){$found[$key] = isset($array[$key]) ?$array[$key] :$default;}return$found;}
Convert a multi-dimensional array into a single-dimensional array.
$array=array('set'=>array('one'=>'something'),'two'=>'other');// Flatten the array$array= Arr::flatten($array);// The array will now bearray('one'=>'something','two'=>'other');
The keys of array values will be discarded.
array
$array
required - Array to flattenarray
publicstaticfunctionflatten($array){$is_assoc= Arr::is_assoc($array);$flat=array();foreach($arrayas$key=>$value){if(is_array($value)){$flat=array_merge($flat, Arr::flatten($value));}else{if($is_assoc){$flat[$key] =$value;}else{$flat[] =$value;}}}return$flat;}
Retrieve a single key from an array. If the key does not exist in the array, the default value will be returned instead.
// Get the value "username" from $_POST, if it exists$username= Arr::get($_POST,'username');// Get the value "sorting" from $_GET, if it exists$sorting= Arr::get($_GET,'sorting');
array
$array
required - Array to extract fromstring
$key
required - Key namemixed
$default
= NULL - Default valuemixed
publicstaticfunctionget($array,$key,$default= NULL){returnisset($array[$key]) ?$array[$key] :$default;}
Test if a value is an array with an additional check for array-like objects.
// Returns TRUEArr::is_array(array());Arr::is_array(newArrayObject);// Returns FALSEArr::is_array(FALSE);Arr::is_array('not an array!');Arr::is_array(Database::instance());
mixed
$value
required - Value to checkboolean
publicstaticfunctionis_array($value){if(is_array($value)){// Definitely an arrayreturnTRUE;}else{// Possibly a Traversable object, functionally the same as an arrayreturn(is_object($value) AND$valueinstanceofTraversable);}}
Tests if an array is associative or not.
// Returns TRUEArr::is_assoc(array('username'=>'john.doe'));// Returns FALSEArr::is_assoc('foo','bar');
array
$array
required - Array to checkboolean
publicstaticfunctionis_assoc(array$array){// Keys of the array$keys=array_keys($array);// If the array keys of the keys match the keys, then the array must// not be associative (e.g. the keys array looked like {0:0, 1:1...}).returnarray_keys($keys) !==$keys;}
Recursive version of array_map, applies one or more callbacks to all elements in an array, including sub-arrays.
// Apply "strip_tags" to every element in the array$array= Arr::map('strip_tags',$array);// Apply $this->filter to every element in the array$array= Arr::map(array(array($this,'filter')),$array);// Apply strip_tags and $this->filter to every element$array= Arr::map(array('strip_tags',array($this,'filter')),$array);
Because you can pass an array of callbacks, if you wish to use an array-form callback
you must nest it in an additional array as above. Calling Arr::map(array($this,'filter'), $array)
will cause an error.
[!!] Unlike array_map, this method requires a callback and will only map
a single array.
mixed
$callbacks
required - Array of callbacks to apply to every element in the arrayarray
$array
required - Array to maparray
$keys
= NULL - Array of keys to apply toarray
publicstaticfunctionmap($callbacks,$array,$keys= NULL){foreach($arrayas$key=>$val){if(is_array($val)){$array[$key] = Arr::map($callbacks,$array[$key]);}elseif( !is_array($keys)orin_array($key,$keys)){if(is_array($callbacks)){foreach($callbacksas$cb){$array[$key] = call_user_func($cb,$array[$key]);}}else{$array[$key] = call_user_func($callbacks,$array[$key]);}}}return$array;}
Merges one or more arrays recursively and preserves all keys. Note that this does not work the same as array_merge_recursive!
$john=array('name'=>'john','children'=>array('fred','paul','sally','jane'));$mary=array('name'=>'mary','children'=>array('jane'));// John and Mary are married, merge them together$john= Arr::merge($john,$mary);// The output of $john will now be:array('name'=>'mary','children'=>array('fred','paul','sally','jane'))
array
$a1
required - Initial arrayarray
$a2
required - ,... array to mergearray
publicstaticfunctionmerge(array$a1,array$a2){$result=array();for($i= 0,$total= func_num_args();$i<$total;$i++){// Get the next array$arr= func_get_arg($i);// Is the array associative?$assoc= Arr::is_assoc($arr);foreach($arras$key=>$val){if(isset($result[$key])){if(is_array($val) ANDis_array($result[$key])){if(Arr::is_assoc($val)){// Associative arrays are merged recursively$result[$key] = Arr::merge($result[$key],$val);}else{// Find the values that are not already present$diff=array_diff($val,$result[$key]);// Indexed arrays are merged to prevent duplicates$result[$key] =array_merge($result[$key],$diff);}}else{if($assoc){// Associative values are replaced$result[$key] =$val;}elseif( ! in_array($val,$result, TRUE)){// Indexed values are added only if they do not yet exist$result[] =$val;}}}else{// New values are added$result[$key] =$val;}}}return$result;}
Overwrites an array with values from input arrays. Keys that do not exist in the first array will not be added!
$a1=array('name'=>'john','mood'=>'happy','food'=>'bacon');$a2=array('name'=>'jack','food'=>'tacos','drink'=>'beer');// Overwrite the values of $a1 with $a2$array= Arr::overwrite($a1,$a2);// The output of $array will now be:array('name'=>'jack','mood'=>'happy','food'=>'tacos')
array
$array1
required - Master arrayarray
$array2
required - Input arrays that will overwrite existing valuesarray
publicstaticfunctionoverwrite($array1,$array2){foreach(array_intersect_key($array2,$array1)as$key=>$value){$array1[$key] =$value;}if(func_num_args() > 2){foreach(array_slice(func_get_args(), 2)as$array2){foreach(array_intersect_key($array2,$array1)as$key=>$value){$array1[$key] =$value;}}}return$array1;}
Gets a value from an array using a dot separated path.
// Get the value of $array['foo']['bar']$value= Arr::path($array,'foo.bar');
Using a wildcard "*" will search intermediate arrays and return an array.
// Get the values of "color" in theme$colors= Arr::path($array,'theme.*.color');// Using an array of keys$colors= Arr::path($array,array('theme','*','color'));
array
$array
required - Array to searchmixed
$path
required - Key path string (delimiter separated) or array of keysmixed
$default
= NULL - Default value if the path is not setstring
$delimiter
= NULL - Key path delimitermixed
publicstaticfunctionpath($array,$path,$default= NULL,$delimiter= NULL){if( ! Arr::is_array($array)){// This is not an array!return$default;}if(is_array($path)){// The path has already been separated into keys$keys=$path;}else{if(array_key_exists($path,$array)){// No need to do extra processingreturn$array[$path];}if($delimiter=== NULL){// Use the default delimiter$delimiter= Arr::$delimiter;}// Remove starting delimiters and spaces$path= ltrim($path,"{$delimiter} ");// Remove ending delimiters, spaces, and wildcards$path= rtrim($path,"{$delimiter} *");// Split the keys by delimiter$keys=explode($delimiter,$path);}do{$key=array_shift($keys);if(ctype_digit($key)){// Make the key an integer$key= (int)$key;}if(isset($array[$key])){if($keys){if(Arr::is_array($array[$key])){// Dig down into the next part of the path$array=$array[$key];}else{// Unable to dig deeperbreak;}}else{// Found the path requestedreturn$array[$key];}}elseif($key==='*'){// Handle wildcards$values=array();foreach($arrayas$arr){if($value= Arr::path($arr, implode('.',$keys))){$values[] =$value;}}if($values){// Found the values requestedreturn$values;}else{// Unable to dig deeperbreak;}}else{// Unable to dig deeperbreak;}}while($keys);// Unable to find the value requestedreturn$default;}
Retrieves muliple single-key values from a list of arrays.
// Get all of the "id" values from a result$ids= Arr::pluck($result,'id');
A list of arrays is an array that contains arrays, eg: array(array $a, array $b, array $c, ...)
array
$array
required - List of arrays to checkstring
$key
required - Key to pluckarray
publicstaticfunctionpluck($array,$key){$values=array();foreach($arrayas$row){if(isset($row[$key])){// Found a value in this row$values[] =$row[$key];}}return$values;}
Fill an array with a range of numbers.
// Fill an array with values 5, 10, 15, 20$values= Arr::range(5, 20);
integer
$step
= integer 10 - Steppinginteger
$max
= integer 100 - Ending numberarray
publicstaticfunctionrange($step= 10,$max= 100){if($step< 1)returnarray();$array=array();for($i=$step;$i<=$max;$i+=$step){$array[$i] =$i;}return$array;}
Set a value on an array by path.
byref array
$array
required - Array to updatestring
$path
required - Pathmixed
$value
required - Value to setstring
$delimiter
= NULL - Path delimiter
publicstaticfunctionset_path( &$array,$path,$value,$delimiter= NULL){if( !$delimiter){// Use the default delimiter$delimiter= Arr::$delimiter;}// Split the keys by delimiter$keys=explode($delimiter,$path);// Set current $array to inner-most array pathwhile(count($keys) > 1){$key=array_shift($keys);if(ctype_digit($key)){// Make the key an integer$key= (int)$key;}if( ! isset($array[$key])){$array[$key] =array();}$array= &$array[$key];}// Set key on inner-most array$array[array_shift($keys)] =$value;}
Adds a value to the beginning of an associative array.
// Add an empty value to the start of a select listArr::unshift($array,'none','Select a value');
byref array
$array
required - Array to modifystring
$key
required - Array key namemixed
$val
required - Array valuearray
publicstaticfunctionunshift(array&$array,$key,$val){$array=array_reverse($array, TRUE);$array[$key] =$val;$array=array_reverse($array, TRUE);return$array;}