W3cubDocs

/CakePHP 4.1

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

Method Summary

  • _filter() protected static

    Callback function for filtering.

  • _matchToken() protected static

    Check a key against a token.

  • _matches() protected static

    Checks whether or not $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.

  • check() public static

    Test whether or not a given path exists in $data.

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

  • dimensions() public static

    Counts the dimensions of an 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.

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

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

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

  • sort() public static

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

Method Detail

_filter() protected static

_filter(mixed $var)

Callback function for filtering.

Parameters

mixed $var

Array to filter.

Returns

bool

_matchToken() protected static

_matchToken(mixed $key, string $token)

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(mixed $data, string $selector)

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

bool

Fitness of expression.

_merge() protected static

_merge(array $stack, array $return)

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.

_simpleOp() protected static

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

Perform a simple insert/remove operation.

Parameters

string $op

The operation to do.

array $data

The data to operate on.

string[] $path

The path to work on.

mixed $values optional

The values to insert when doing inserts.

Returns

array

data.

_splitConditions() protected static

_splitConditions(string $token)

Split token conditions

Parameters

string $token

the token being splitted.

Returns

array

[token, conditions] with token splitted

_squash() protected static

_squash(array $data, mixed $key)

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

Parameters

array $data

The data to squash.

mixed $key optional

The key for the data.

Returns

array

apply() public static

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.

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.

Links

check() public static

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.

Parameters

array $data

The data to check.

string $path

The path to check for.

Returns

bool

Existence of path.

See Also

\Cake\Utility\Hash::extract()

Links

combine() public static

combine(array $data, mixed $keyPath, mixed $valuePath, ?string $groupPath)

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|string[]|null $keyPath

A dot-separated string.

string|string[]|null $valuePath optional

A dot-separated string.

string|null $groupPath optional

A dot-separated string.

Returns

array

Combined array

Throws

RuntimeException
When keys and values count is unequal.

Links

contains() public static

contains(array $data, array $needle)

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

true If $data contains $needle, false otherwise

Links

diff() public static

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.

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

Links

dimensions() public static

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.

Parameters

array $data

Array to count dimensions on

Returns

int

The number of dimensions in $data

Links

expand() public static

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

Parameters

array $data

Flattened array

string $separator optional

The delimiter used

Returns

array

Links

extract() public static

extract(mixed $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 $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

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.

Links

filter() public static

filter(array $data, mixed $callback)

Recursively filters a data set.

Parameters

array $data

Either an array to filter, or value when in callback

callable|array $callback optional

A function to filter the data with. Defaults to static::_filter() Which strips out all non-zero empty values.

Returns

array

Filtered array

Links

flatten() public static

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

Parameters

array $data

Array to flatten

string $separator optional

String used to separate array key elements in a path, defaults to '.'

Returns

array

Links

format() public static

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.

Parameters

array $data

Source array from which to extract the data

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

string[]|null

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

See Also

\Cake\Utility\sprintf()

\Cake\Utility\Hash::extract()

Links

get() public static

get(mixed $data, mixed $path, mixed $default)

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|int|string[]|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

The value fetched from the array, or null.

Throws

InvalidArgumentException

Links

insert() public static

insert(array $data, string $path, mixed $values)

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

The data with $values inserted.

Links

map() public static

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.

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.

Links

maxDimensions() public static

maxDimensions(array $data)

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

The maximum number of dimensions in $data

Links

merge() public static

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

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

Links

mergeDiff() public static

mergeDiff(array $data, array $compare)

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.

Links

nest() public static

nest(array $data, array $options)

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 optional

Options are:

Returns

array[]

of results, nested

Throws

InvalidArgumentException
When providing invalid data.

See Also

\Cake\Utility\Hash::extract()

Links

normalize() public static

normalize(array $data, bool $assoc)

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.

Returns

array

Links

numeric() public static

numeric(array $data)

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

Parameters

array $data

The array to check.

Returns

bool

true if values are numeric, false otherwise

Links

reduce() public static

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

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.

Links

remove() public static

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.

Parameters

array $data

The data to operate on

string $path

A path expression to use to remove.

Returns

array

The modified array.

Links

sort() public static

sort(array $data, string $path, mixed $dir, mixed $type)

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 $type optional

See direction types above. Defaults to 'regular'.

Returns

array

Sorted array of data

Links

© 2005–present 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/4.1/class-Cake.Utility.Hash.html