Library of array functions for manipulating and extracting data from arrays or 'sets' of data.
Hash provides an improved interface, more consistent and predictable set of features over Set. While it lacks the spotty support for pseudo Xpath, its more fully featured dot notation provides similar features in a more consistent implementation.
Helper method for sort() Squashes an array to a single hash so it can be sorted.
Apply a callback to a set of extracted values using $function. The function will get the extracted values as the first argument.
Test whether or not a given path exists in $data. This method uses the same path syntax as Hash::extract()
Creates an associative array using $keyPath as the path to build its keys, and optionally $valuePath as path to get the values. If $valuePath is not specified, all values will be initialized to null (useful for Hash::merge). You can optionally group the values by what is obtained when following the path specified in $groupPath.
Computes the difference between two complex arrays. This method differs from the built-in array_diff() in that it will preserve keys and work on multi-dimensional arrays.
Counts the dimensions of an array. Only considers the dimension of the first element in the array.
Gets the values from an array matching the $path expression. The path expression is a dot separated expression, that can contain a set of patterns and expressions:
Collapses a multi-dimensional array into a single dimension, using a delimited array path for each array element's key, i.e. [['Foo' => ['Bar' => 'Far']]] becomes ['0.Foo.Bar' => 'Far'].)
Returns a formatted series of values extracted from $data, using $format as the format and $paths as the values to extract.
Get a single value specified by $path out of $data. Does not support the full dot notation feature set, but is faster for simple read operations.
Insert $values into an array with the given $path. You can use {n} and {s} elements to insert $data multiple times.
Map a callback across all elements in a set. Can be provided a path to only modify slices of the set.
Counts the dimensions of all array elements. Useful for finding the maximum number of dimensions in a mixed array.
array_merge and array_merge_recursive. $function. Remove data matching $path from the $data array. You can use {n} and {s} to remove multiple elements from $data.
_filter( array $var )
Callback function for filtering.
$var _matchToken( string $key , string $token )
Check a key against a token.
$key $token _matches( array|ArrayAccess $data , string $selector )
Checks whether or not $data matches the attribute patterns
$data $selector _merge( array $stack , array $return )
Merge helper function to reduce duplicated code between merge() and expand().
$stack $return _simpleOp( string $op , array $data , array $path , mixed $values null )
Perform a simple insert/remove operation.
$op $data $path $values optional null _splitConditions( string $token )
Split token conditions
$token _squash( array $data , string|null $key null )
Helper method for sort() Squashes an array to a single hash so it can be sorted.
$data $key optional null apply( array $data , string $path , callable $function )
Apply a callback to a set of extracted values using $function. The function will get the extracted values as the first argument.
You can easily count the results of an extract using apply(). For example to count the comments on an Article:
$count = Hash::apply($data, 'Article.Comment.{n}', 'count'); You could also use a function like array_sum to sum the results.
$total = Hash::apply($data, '{n}.Item.price', 'array_sum'); $data $path $function check( array $data , string $path )
Test whether or not a given path exists in $data. This method uses the same path syntax as Hash::extract()
Checking for paths that could target more than one element will make sure that at least one matching element exists.
$data $path combine( array $data , string $keyPath , string|null $valuePath null , string|null $groupPath null )
Creates an associative array using $keyPath as the path to build its keys, and optionally $valuePath as path to get the values. If $valuePath is not specified, all values will be initialized to null (useful for Hash::merge). You can optionally group the values by what is obtained when following the path specified in $groupPath.
$data $keyPath $valuePath optional null $groupPath optional null contains( array $data , array $needle )
Determines if one array contains the exact keys and values of another.
$data $needle diff( array $data , array $compare )
Computes the difference between two complex arrays. This method differs from the built-in array_diff() in that it will preserve keys and work on multi-dimensional arrays.
$data $compare Returns the key => value pairs that are not common in $data and $compare The expression for this function is ($data - $compare) + ($compare - ($data - $compare))
dimensions( array $data )
Counts the dimensions of an array. Only considers the dimension of the first element in the array.
If you have an un-even or heterogeneous array, consider using Hash::maxDimensions() to get the dimensions of the array.
$data expand( array $data , string $separator '.' )
Expands a flat array to a nested array.
For example, unflattens an array that was collapsed with Hash::flatten() into a multi-dimensional array. So, ['0.Foo.Bar' => 'Far'] becomes [['Foo' => ['Bar' => 'Far']]].
$data $separator optional '.' extract( array|ArrayAccess $data , string $path )
Gets the values from an array matching the $path expression. The path expression is a dot separated expression, that can contain a set of patterns and expressions:
{n} Matches any numeric key, or integer.{s} Matches any string key.{*} Matches any value.Foo Matches any key with the exact same value.There are a number of attribute operators:
=, != Equality.>, <, >=, <= Value comparison.=/.../ Regular expression pattern match.Given a set of User array data, from a $User->find('all') call:
1.User.name Get the name of the user at index 1.{n}.User.name Get the name of every user in the set of users.{n}.User[id] Get the name of every user with an id key.{n}.User[id>=2] Get the name of every user with an id key greater than or equal to 2.{n}.User[username=/^paul/] Get User elements with username matching ^paul.{n}.User[id=1].name Get the Users name with id matching 1.$data $path An array of the extracted values. Returns an empty array if there are no matches.
filter( array $data , callable|array $callback ['self', '_filter'] )
Recursively filters a data set.
$data $callback optional ['self', '_filter'] A function to filter the data with. Defaults to static::_filter() Which strips out all non-zero empty values.
flatten( array $data , string $separator '.' )
Collapses a multi-dimensional array into a single dimension, using a delimited array path for each array element's key, i.e. [['Foo' => ['Bar' => 'Far']]] becomes ['0.Foo.Bar' => 'Far'].)
$data $separator optional '.' format( array $data , array $paths , string $format )
Returns a formatted series of values extracted from $data, using $format as the format and $paths as the values to extract.
Usage:
$result = Hash::format($users, ['{n}.User.id', '{n}.User.name'], '%s : %s'); The $format string can use any format options that vsprintf() and sprintf() do.
$data $paths $format $path and formatted with $formatget( array|ArrayAccess $data , string|array $path , mixed $default null )
Get a single value specified by $path out of $data. Does not support the full dot notation feature set, but is faster for simple read operations.
$data Array of data or object implementing \ArrayAccess interface to operate on.
$path The path being searched for. Either a dot separated string, or an array of path segments.
$default optional null insert( array $data , string $path , array|null $values null )
Insert $values into an array with the given $path. You can use {n} and {s} elements to insert $data multiple times.
$data $path $values optional null map( array $data , string $path , callable $function )
Map a callback across all elements in a set. Can be provided a path to only modify slices of the set.
$data $path $function maxDimensions( array $data )
Counts the dimensions of all array elements. Useful for finding the maximum number of dimensions in a mixed array.
$data merge( array $data , mixed $merge )
This function can be thought of as a hybrid between PHP's array_merge and array_merge_recursive.
The difference between this method and the built-in ones, is that if an array key contains another array, then Hash::merge() will behave in a recursive fashion (unlike array_merge). But it will not act recursively for keys that contain scalar values (unlike array_merge_recursive).
Note: This function will work with an unlimited amount of arguments and typecasts non-array parameters into arrays.
$data $merge mergeDiff( array $data , array $compare )
Merges the difference between $data and $compare onto $data.
$data $compare nest( array $data , array $options [] )
Takes in a flat array and returns a nested array
children The key name to use in the resultset for children.idPath The path to a key that identifies each entry. Should be compatible with Hash::extract(). Defaults to {n}.$alias.id
parentPath The path to a key that identifies the parent of each entry. Should be compatible with Hash::extract(). Defaults to {n}.$alias.parent_id
root The id of the desired top-most result.$data $options optional [] normalize( array $data , boolean $assoc true )
Normalizes an array, and converts it to a standard format.
$data $assoc optional true numeric( array $data )
Checks to see if all the values in the array are numeric
$data reduce( array $data , string $path , callable $function )
Reduce a set of extracted values using $function.
$data $path $function remove( array $data , string $path )
Remove data matching $path from the $data array. You can use {n} and {s} to remove multiple elements from $data.
$data $path sort( array $data , string $path , string $dir 'asc' , array|string $type 'regular' )
Sorts an array by any value, determined by a Set-compatible path
asc Sort ascending.desc Sort descending.regular For regular sorting (don't change types)numeric Compare values numericallystring Compare values as stringslocale Compare items as strings, based on the current localenatural Compare items as strings using "natural ordering" in a human friendly way Will sort foo10 below foo2 as an example.To do case insensitive sorting, pass the type as an array as follows:
Hash::sort($data, 'some.attribute', 'asc', ['type' => 'regular', 'ignoreCase' => true]);
When using the array form, type defaults to 'regular'. The ignoreCase option defaults to false.
$data $path $dir optional 'asc' $type optional 'regular'
© 2005–2017 The Cake Software Foundation, Inc.
Licensed under the MIT License.
CakePHP is a registered trademark of Cake Software Foundation, Inc.
We are not endorsed by or affiliated with CakePHP.
https://api.cakephp.org/3.4/class-Cake.Utility.Hash.html