Class Hash

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.

Namespace: Cake\Utility
Link: https://book.cakephp.org/5/en/core-libraries/hash.html

Method Summary

_filter() protected static

Callback function for filtering.
_matchToken() protected static

Check a key against a token.
_matches() protected static

Checks whether $data matches the attribute patterns
_merge() protected static

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

Perform a simple insert/remove operation.
_splitConditions() protected static

Split token conditions
_squash() protected static

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

Apply a callback to a set of extracted values using $function. The function will get the extracted values as the first argument.
check() public static

Test whether a given path exists in $data. This method uses the same path syntax as Hash::extract()
combine() public static

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.
contains() public static

Determines if one array contains the exact keys and values of another.
diff() public static

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.
dimensions() public static

Counts the dimensions of an array. Only considers the dimension of the first element in the array.
expand() public static

Expands a flat array to a nested array.
extract() public static

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:
filter() public static

Recursively filters a data set.
flatten() public static

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'].)
format() public static

Returns a formatted series of values extracted from $data, using $format as the format and $paths as the values to extract.
get() public static

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() public static

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

Map a callback across all elements in a set. Can be provided a path to only modify slices of the set.
maxDimensions() public static

Counts the dimensions of all array elements. Useful for finding the maximum number of dimensions in a mixed array.
merge() public static

This function can be thought of as a hybrid between PHP's array_merge and array_merge_recursive.
mergeDiff() public static

Merges the difference between $data and $compare onto $data.
nest() public static

Takes in a flat array and returns a nested array
normalize() public static

Normalizes an array, and converts it to a standard format.
numeric() public static

Checks to see if all the values in the array are numeric
reduce() public static

Reduce a set of extracted values using $function.
remove() public static

Remove data matching $path from the $data array. You can use {n} and {s} to remove multiple elements from $data.
sort() public static

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

Method Detail

_filter() ¶ protected static

_filter(mixed $var): bool

Callback function for filtering.

Parameters

mixed $var: Array to filter.

Returns

bool

_matchToken() ¶ protected static

_matchToken(mixed $key, string $token): bool

Check a key against a token.

Parameters

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

Returns

bool

_matches() ¶ protected static

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

Checks whether $data matches the attribute patterns

Parameters

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

Returns

bool

_merge() ¶ protected static

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

Returns

void

_simpleOp() ¶ protected static

_simpleOp(string $op, array $data, array<string> $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<string> $path: The path to work on.
mixed $values optional: The values to insert when doing inserts.

Returns

array

_splitConditions() ¶ protected static

_splitConditions(string $token): array

Split token conditions

Parameters

string $token: the token being split.

Returns

array

_squash() ¶ protected static

_squash(array $data, string|int|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|int|null $key optional: The key for the data.

Returns

array

apply() ¶ public static

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

Links

https://book.cakephp.org/5/en/core-libraries/hash.html#Cake\Utility\Hash::apply

check() ¶ public static

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

Test whether 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

bool

Links

https://book.cakephp.org/5/en/core-libraries/hash.html#Cake\Utility\Hash::check

combine() ¶ public static

combine(array $data, array<string>|string|null $keyPath, array<string>|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
array<string>|string|null $keyPath: A dot-separated string.
array<string>|string|null $valuePath optional: A dot-separated string.
string|null $groupPath optional: A dot-separated string.

Returns

array

Throws

InvalidArgumentException
When keys and values count is unequal.

Links

https://book.cakephp.org/5/en/core-libraries/hash.html#Cake\Utility\Hash::combine

contains() ¶ public static

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

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

bool

Links

https://book.cakephp.org/5/en/core-libraries/hash.html#Cake\Utility\Hash::contains

diff() ¶ public static

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

Links

https://book.cakephp.org/5/en/core-libraries/hash.html#Cake\Utility\Hash::diff

dimensions() ¶ public static

dimensions(array $data): int

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

int

Links

https://book.cakephp.org/5/en/core-libraries/hash.html#Cake\Utility\Hash::dimensions

expand() ¶ public static

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 optional: The delimiter used

Returns

array

Links

https://book.cakephp.org/5/en/core-libraries/hash.html#Cake\Utility\Hash::expand

extract() ¶ public static

extract(ArrayAccess|array $data, string $path): ArrayAccess|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:

{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 $usersTable->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

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

Returns

ArrayAccess|array

Links

https://book.cakephp.org/5/en/core-libraries/hash.html#Cake\Utility\Hash::extract

filter() ¶ public static

filter(array $data, callable|null $callback = null): array

Recursively filters a data set.

Parameters

array $data: Either an array to filter, or value when in callback
callable|null $callback optional: A function to filter the data with. Defaults to all non-empty or zero values.

Returns

array

Links

https://book.cakephp.org/5/en/core-libraries/hash.html#Cake\Utility\Hash::filter

flatten() ¶ public static

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 optional: String used to separate array key elements in a path, defaults to '.'

Returns

array

Links

https://book.cakephp.org/5/en/core-libraries/hash.html#Cake\Utility\Hash::flatten

format() ¶ public static

format(array $data, array<string> $paths, string $format): array<string>|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<string> $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<string>|null

Links

https://book.cakephp.org/5/en/core-libraries/hash.html#Cake\Utility\Hash::format

get() ¶ public static

get(ArrayAccess|array $data, array<string>|string|int|null $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

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

Returns

mixed

Throws

InvalidArgumentException

Links

https://book.cakephp.org/5/en/core-libraries/hash.html#Cake\Utility\Hash::get

insert() ¶ public static

insert(array $data, string $path, mixed $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.
mixed $values optional: The values to insert.

Returns

array

Links

https://book.cakephp.org/5/en/core-libraries/hash.html#Cake\Utility\Hash::insert

map() ¶ public static

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

Links

https://book.cakephp.org/5/en/core-libraries/hash.html#Cake\Utility\Hash::map

maxDimensions() ¶ public static

maxDimensions(array $data): int

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

int

Links

https://book.cakephp.org/5/en/core-libraries/hash.html#Cake\Utility\Hash::maxDimensions

merge() ¶ public static

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

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

Links

https://book.cakephp.org/5/en/core-libraries/hash.html#Cake\Utility\Hash::merge

mergeDiff() ¶ public static

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

Links

https://book.cakephp.org/5/en/core-libraries/hash.html#Cake\Utility\Hash::mergeDiff

nest() ¶ public static

nest(array $data, array<string, string|null> $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<string, string|null> $options optional: Options.

Returns

array<array>

Throws

InvalidArgumentException
When providing invalid data.

Links

https://book.cakephp.org/5/en/core-libraries/hash.html#Cake\Utility\Hash::nest

normalize() ¶ public static

normalize(array $data, bool $assoc = true, mixed $default = null): array

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

Parameters

array $data: List to normalize
bool $assoc optional: If true, $data will be converted to an associative array.
mixed $default optional: The default value to use when a top level numeric key is converted to associative form.

Returns

array

Links

https://book.cakephp.org/5/en/core-libraries/hash.html#Cake\Utility\Hash::normalize

numeric() ¶ public static

numeric(array $data): bool

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

Parameters

array $data: The array to check.

Returns

bool

Links

https://book.cakephp.org/5/en/core-libraries/hash.html#Cake\Utility\Hash::numeric

reduce() ¶ public static

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

Links

https://book.cakephp.org/5/en/core-libraries/hash.html#Cake\Utility\Hash::reduce

remove() ¶ public static

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

Links

https://book.cakephp.org/5/en/core-libraries/hash.html#Cake\Utility\Hash::remove

sort() ¶ public static

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

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

Sort directions

asc or \SORT_ASC Sort ascending.
desc or \SORT_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|int $dir optional: See directions above. Defaults to 'asc'.
array<string, mixed>|string $type optional: See direction types above. Defaults to 'regular'.

Returns

array

Links

https://book.cakephp.org/5/en/core-libraries/hash.html#Cake\Utility\Hash::sort

Namespaces

Class Hash

Method Summary

_filter() protected static

_matchToken() protected static

_matches() protected static

_merge() protected static

_simpleOp() protected static

_splitConditions() protected static

_squash() protected static

apply() public static

check() public static

combine() public static

contains() public static

diff() public static

dimensions() public static

expand() public static

extract() public static

filter() public static

flatten() public static

format() public static

get() public static

insert() public static

map() public static

maxDimensions() public static

merge() public static

mergeDiff() public static

nest() public static

normalize() public static

numeric() public static

reduce() public static

remove() public static

sort() public static

Method Detail

_filter() ¶ protected static

Parameters

Returns

_matchToken() ¶ protected static

Parameters

Returns

_matches() ¶ protected static

Parameters

Returns

_merge() ¶ protected static

Parameters

Returns

_simpleOp() ¶ protected static

Parameters

Returns

_splitConditions() ¶ protected static

Parameters

Returns

_squash() ¶ protected static

Parameters

Returns

apply() ¶ public static

Example

Parameters

Returns

Links

check() ¶ public static

Parameters

Returns

See Also

Links

combine() ¶ public static

Parameters

Returns

Throws

Links

contains() ¶ public static

Parameters

Returns

Links

diff() ¶ public static

Parameters

Returns

Links

dimensions() ¶ public static

Parameters