\Cake\UtilityHash

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.

Summary

Methods

Properties

Constants

get()
extract()
insert()
remove()
combine()
format()
contains()
check()
filter()
flatten()
expand()
merge()
numeric()
dimensions()
maxDimensions()
map()
reduce()
apply()
sort()
diff()
mergeDiff()
normalize()
nest()

No public properties found

No constants found

_splitConditions()
_matchToken()
_matches()
_simpleOp()
_filter()
_merge()
_squash()

No protected properties found

N/A

No private methods found

No private properties found

N/A

Methods

get()

get(array|\ArrayAccess  $data, string|array  $path, mixed  $default = null) : mixed

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.

Parameters

array\|\ArrayAccess	$data	Array of data or object implementing \ArrayAccess interface to operate on.
string\|array	$path	The path being searched for. Either a dot separated string, or an array of path segments.
mixed	$default	The return value when the path does not exist

Throws

\InvalidArgumentException

Returns

mixed —

The value fetched from the array, or null.

extract()

extract(array|\ArrayAccess  $data, string  $path) : array|\ArrayAccess

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].name Get the name of every user with an id key.
{n}.User[id>=2].name 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.

Parameters

array\|\ArrayAccess	$data	The data to extract from.
string	$path	The path to extract.

Returns

array|\ArrayAccess —

An array of the extracted values. Returns an empty array if there are no matches.

insert()

insert(array  $data, string  $path, array|null  $values = null) : array

Insert $values into an array with the given $path. You can use `{n}` and `{s}` elements to insert $data multiple times.

Parameters

array	$data	The data to insert into.
string	$path	The path to insert at.
array\|null	$values	The values to insert.

Returns

array —

The data with $values inserted.

remove()

remove(array  $data, string  $path) : array

Remove data matching $path from the $data array.

You can use {n} and {s} to remove multiple elements from $data.

Parameters

array	$data	The data to operate on
string	$path	A path expression to use to remove.

Returns

array —

The modified array.

combine()

combine(array  $data, string  $keyPath, string|null  $valuePath = null, string|null  $groupPath = null) : array

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`.

Parameters

array	$data	Array from where to extract keys and values
string	$keyPath	A dot-separated string.
string\|null	$valuePath	A dot-separated string.
string\|null	$groupPath	A dot-separated string.

Throws

\RuntimeException: When keys and values count is unequal.

Returns

array —

Combined array

format()

format(array  $data, array  $paths, string  $format) : array|null

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.

Parameters

array	$data	Source array from which to extract the data
array	$paths	An array containing one or more Hash::extract()-style key paths
string	$format	Format string into which values will be inserted, see sprintf()

Returns

array|null —

An array of strings extracted from $path and formatted with $format

contains()

contains(array  $data, array  $needle) : boolean

Determines if one array contains the exact keys and values of another.

Parameters

array	$data	The data to search through.
array	$needle	The values to file in $data

Returns

boolean —

true If $data contains $needle, false otherwise

check()

check(array  $data, string  $path) : boolean

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.

Parameters

array	$data	The data to check.
string	$path	The path to check for.

Returns

boolean —

Existence of path.

filter()

filter(array  $data, callable|array  $callback = array('self', '_filter')) : array

Recursively filters a data set.

Parameters

array	$data	Either an array to filter, or value when in callback
callable\|array	$callback	A function to filter the data with. Defaults to `static::_filter()` Which strips out all non-zero empty values.

Returns

array —

Filtered array

flatten()

flatten(array  $data, string  $separator = '.') : array

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'].)

Parameters

array	$data	Array to flatten
string	$separator	String used to separate array key elements in a path, defaults to '.'

Returns

array

expand()

expand(array  $data, string  $separator = '.') : array

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']]].

Parameters

array	$data	Flattened array
string	$separator	The delimiter used

Returns

array

merge()

merge(array  $data, mixed  $merge) : array

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.

Parameters

array	$data	Array to be merged
mixed	$merge	Array to merge with. The argument and all trailing arguments will be array cast when merged

Returns

array —

Merged array

numeric()

numeric(array  $data) : boolean

Checks to see if all the values in the array are numeric

Parameters

array

$data

The array to check.

Returns

boolean —

true if values are numeric, false otherwise

dimensions()

dimensions(array  $data) : integer

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.

Parameters

array

$data

Array to count dimensions on

Returns

integer —

The number of dimensions in $data

maxDimensions()

maxDimensions(array  $data) : integer

Counts the dimensions of *all* array elements. Useful for finding the maximum number of dimensions in a mixed array.

Parameters

array

$data

Array to count dimensions on

Returns

integer —

The maximum number of dimensions in $data

map()

map(array  $data, string  $path, callable  $function) : array

Map a callback across all elements in a set.

Can be provided a path to only modify slices of the set.

Parameters

array	$data	The data to map over, and extract data out of.
string	$path	The path to extract for mapping over.
callable	$function	The function to call on each extracted value.

Returns

array —

An array of the modified values.

reduce()

reduce(array  $data, string  $path, callable  $function) : mixed

Reduce a set of extracted values using `$function`.

Parameters

array	$data	The data to reduce.
string	$path	The path to extract from $data.
callable	$function	The function to call on each extracted value.

Returns

mixed —

The reduced value.

apply()

apply(array  $data, string  $path, callable  $function) : mixed

Apply a callback to a set of extracted values using `$function`.

The function will get the extracted values as the first argument.

Example

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');

Parameters

array	$data	The data to reduce.
string	$path	The path to extract from $data.
callable	$function	The function to call on each extracted value.

Returns

mixed —

The results of the applied method.

sort()

sort(array  $data, string  $path, string  $dir = 'asc', array|string  $type = 'regular') : array

Sorts an array by any value, determined by a Set-compatible path

Sort directions

asc Sort ascending.
desc Sort descending.

Sort types

regular For regular sorting (don't change types)
numeric Compare values numerically
string Compare values as strings
locale Compare items as strings, based on the current locale
natural 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.

Parameters

array	$data	An array of data to sort
string	$path	A Set-compatible path to the array value
string	$dir	See directions above. Defaults to 'asc'.
array\|string	$type	See direction types above. Defaults to 'regular'.

Returns

array —

Sorted array of data

diff()

diff(array  $data, array  $compare) : array

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.

Parameters

array	$data	First value
array	$compare	Second value

Returns

array —

Returns the key => value pairs that are not common in $data and $compare The expression for this function is ($data - $compare) + ($compare - ($data - $compare))

mergeDiff()

mergeDiff(array  $data, array  $compare) : array

Merges the difference between $data and $compare onto $data.

Parameters

array	$data	The data to append onto.
array	$compare	The data to compare and append onto.

Returns

array —

The merged array.

normalize()

normalize(array  $data, boolean  $assoc = true) : array

Normalizes an array, and converts it to a standard format.

Parameters

array	$data	List to normalize
boolean	$assoc	If true, $data will be converted to an associative array.

Returns

array

nest()

nest(array  $data, array  $options = array()) : array

Takes in a flat array and returns a nested array

Options:

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.

Parameters

array	$data	The data to nest.
array	$options	Options are:

Throws

\InvalidArgumentException: When providing invalid data.

Returns

array —

of results, nested

_splitConditions()

_splitConditions(string  $token) : array

Split token conditions

Parameters

string

$token

the token being splitted.

Returns

array —

[token, conditions] with token splitted

_matchToken()

_matchToken(string  $key, string  $token) : boolean

Check a key against a token.

Parameters

string	$key	The key in the array being searched.
string	$token	The token being matched.

Returns

boolean

_matches()

_matches(array|\ArrayAccess  $data, string  $selector) : boolean

Checks whether or not $data matches the attribute patterns

Parameters

array\|\ArrayAccess	$data	Array of data to match.
string	$selector	The patterns to match.

Returns

boolean —

Fitness of expression.

_simpleOp()

_simpleOp(string  $op, array  $data, array  $path, mixed  $values = null) : array

Perform a simple insert/remove operation.

Parameters

string	$op	The operation to do.
array	$data	The data to operate on.
array	$path	The path to work on.
mixed	$values	The values to insert when doing inserts.

Returns

array —

data.

_filter()

_filter(mixed  $var) : boolean

Callback function for filtering.

Parameters

mixed

$var

Array to filter.

Returns

boolean

_merge()

_merge(array  $stack, array  $return) : void

Merge helper function to reduce duplicated code between merge() and expand().

Parameters

array	$stack	The stack of operations to work with.
array	$return	The return value to operate on.

_squash()

_squash(array  $data, string|null  $key = null) : array

Helper method for sort() Squashes an array to a single hash so it can be sorted.

Parameters

array	$data	The data to squash.
string\|null	$key	The key for the data.

Returns

array