类 Hash

用于操作和提取数组或数据集中数据的数组函数库。

Hash 提供了改进的接口，比 Set 更加一致和可预测的功能集。虽然它缺乏对伪 Xpath 的支持，但它更加完整的功能点符号提供了类似的功能，以更一致的方式实现。

命名空间: Cake\Utility
链接: https://book.cakephp.com.cn/5/en/core-libraries/hash.html

方法概述

_filter() protected static

用于过滤的回调函数。
_matchToken() protected static

检查键是否与令牌匹配。
_matches() protected static

检查 $data 是否与属性模式匹配。
_merge() protected static

合并辅助函数，减少 merge() 和 expand() 之间的重复代码。
_simpleOp() protected static

执行简单的插入/删除操作。
_splitConditions() protected static

拆分令牌条件。
_squash() protected static

sort() 的辅助方法，将数组压缩成单个哈希以便排序。
apply() public static

使用 $function 将回调应用于一组提取的值。该函数将提取的值作为第一个参数。
check() public static

测试给定路径是否在 $data 中存在。此方法使用与 Hash::extract() 相同的路径语法。
combine() public static

使用 $keyPath 作为构建其键的路径，并选择使用 $valuePath 作为获取值的路径，来创建关联数组。如果未指定 $valuePath，则所有值将初始化为 null（对于 Hash::merge 非常有用）。您可以选择根据按照 $groupPath 中指定的路径获得的值对值进行分组。
contains() public static

确定一个数组是否包含另一个数组的完全相同的键和值。
diff() public static

计算两个复杂数组之间的差异。此方法不同于内置的 array_diff()，因为它将保留键并作用于多维数组。
dimensions() public static

计算数组的维度。只考虑数组中第一个元素的维度。
expand() public static

将扁平数组扩展为嵌套数组。
extract() public static

获取与 $path 表达式匹配的数组中的值。路径表达式是一个用点分隔的表达式，可以包含一组模式和表达式。
filter() public static

递归地过滤数据集。
flatten() public static

将多维数组折叠成单维数组，使用分隔的数组路径作为每个数组元素的键，例如：[['Foo' => ['Bar' => 'Far']]] 变为 ['0.Foo.Bar' => 'Far']。
format() public static

返回从 $data 中提取的一系列格式化值，使用 $format 作为格式，使用 $paths 作为要提取的值。
get() public static

从 $data 中获取 $path 指定的单个值。不支持完整的点符号功能集，但对于简单的读取操作更快。
insert() public static

使用给定的 $path 将 $values 插入数组。您可以使用 {n} 和 {s} 元素多次插入 $data。
map() public static

将回调映射到集合中的所有元素。可以提供路径来仅修改集合的切片。
maxDimensions() public static

计算所有数组元素的维度。对于在混合数组中查找最大维度很有用。
merge() public static

此函数可以看作是 PHP 的 array_merge 和 array_merge_recursive 的混合体。
mergeDiff() public static

将 $data 和 $compare 之间的差异合并到 $data 上。
nest() public static

接收扁平数组并返回嵌套数组。
normalize() public static

规范化数组，并将其转换为标准格式。
numeric() public static

检查数组中的所有值是否都是数字。
reduce() public static

使用 $function 减少一组提取的值。
remove() public static

从 $data 数组中删除与 $path 匹配的数据。您可以使用 {n} 和 {s} 从 $data 中删除多个元素。
sort() public static

根据任何值对数组进行排序，由 Set 兼容的路径确定。

方法详情

_filter() ¶ protected static

_filter(mixed $var): bool

用于过滤的回调函数。

参数

mixed $var: 要过滤的数组。

bool

_matchToken() ¶ protected static

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

检查键是否与令牌匹配。

参数

mixed $key: 正在搜索的数组中的键。
string $token: 正在匹配的令牌。

bool

_matches() ¶ protected static

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

检查 $data 是否与属性模式匹配。

参数

ArrayAccess|array $data: 要匹配的数据数组。
string $selector: 要匹配的模式。

bool

_merge() ¶ protected static

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

合并辅助函数，减少 merge() 和 expand() 之间的重复代码。

参数

array $stack: 要使用的操作堆栈。
array $return: 要操作的返回值。

void

_simpleOp() ¶ protected static

_simpleOp(string $op, ArrayAccess|array $data, list<string> $path, mixed $values = null): ArrayAccess|array

执行简单的插入/删除操作。

参数

string $op: 要执行的操作。
ArrayAccess|array $data: 要操作的数据。
list<string> $path: 要操作的路径。
mixed $values optional: 执行插入时要插入的值。

ArrayAccess|array

_splitConditions() ¶ protected static

_splitConditions(string $token): array

拆分令牌条件。

参数

string $token: 要拆分的令牌。

array

_squash() ¶ protected static

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

sort() 的辅助方法，将数组压缩成单个哈希以便排序。

参数

array $data: 要压缩的数据。
string|int|null $key 可选: 数据的键。

array

apply() ¶ public static

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

使用 $function 将回调应用于一组提取的值。该函数将提取的值作为第一个参数。

示例

您可以轻松地使用 apply() 来计算提取结果的计数。例如，要计算文章的评论数

$count = Hash::apply($data, 'Article.Comment.{n}', 'count');

您也可以使用 array_sum 这样的函数来对结果求和。

$total = Hash::apply($data, '{n}.Item.price', 'array_sum');

参数

array $data: 要减少的数据。
string $path: 从 $data 中提取的路径。
callable $function: 对每个提取的值调用的函数。

混合

链接

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

check() ¶ public static

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

测试给定路径是否在 $data 中存在。此方法使用与 Hash::extract() 相同的路径语法。

检查可能针对多个元素的路径将确保至少存在一个匹配的元素。

参数

array $data: 要检查的数据。
string $path: 要检查的路径。

bool

另请参阅

\Cake\Utility\Hash::extract()

链接

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

combine() ¶ public static

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

使用 $keyPath 作为构建其键的路径，并选择使用 $valuePath 作为获取值的路径，来创建关联数组。如果未指定 $valuePath，则所有值将初始化为 null（对于 Hash::merge 非常有用）。您可以选择根据按照 $groupPath 中指定的路径获得的值对值进行分组。

参数

array $data: 从中提取键和值的数组
list<string>|string|null $keyPath: 一个点分隔的字符串。
list<string>|string|null $valuePath 可选: 一个点分隔的字符串。
string|null $groupPath 可选: 一个点分隔的字符串。

array

抛出

InvalidArgumentException
当键和值数量不相等时。

链接

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

contains() ¶ public static

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

确定一个数组是否包含另一个数组的完全相同的键和值。

参数

array $data: 要搜索的数据。
array $needle: 要在 $data 中查找的值

bool

链接

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

diff() ¶ public static

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

计算两个复杂数组之间的差异。此方法不同于内置的 array_diff()，因为它将保留键并作用于多维数组。

参数

array $data: 第一个值
array $compare: 第二个值

array

链接

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

dimensions() ¶ public static

dimensions(array $data): int

计算数组的维度。只考虑数组中第一个元素的维度。

如果您有一个不均匀或异构数组，请考虑使用 Hash::maxDimensions() 来获取数组的维度。

参数

array $data: 要计算维度的数组

int

链接

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

expand() ¶ public static

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

将扁平数组扩展为嵌套数组。

例如，将使用 Hash::flatten() 压缩的数组展开为多维数组。因此，['0.Foo.Bar' => 'Far'] 变为 [['Foo' => ['Bar' => 'Far']]]。

参数

array $data: 扁平化的数组
string $separator 可选: 使用的分隔符

array

链接

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

extract() ¶ public static

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

获取与 $path 表达式匹配的数组中的值。路径表达式是一个用点分隔的表达式，可以包含一组模式和表达式。

{n} 匹配任何数字键或整数。
{s} 匹配任何字符串键。
{*} 匹配任何值。
Foo 匹配具有完全相同值的任何键。

有一些属性运算符

=, != 相等性。
- >, <, >=, <= 值比较。
- =/.../ 正则表达式模式匹配。

给定一组用户数组数据，来自 $usersTable->find('all') 调用

1.User.name 获取索引 1 处用户的姓名。
{n}.User.name 获取用户集中每个用户的姓名。
{n}.User[id].name 获取每个具有 id 键的用户的姓名。
{n}.User[id>=2].name 获取 id 键大于或等于 2 的每个用户的姓名。
{n}.User[username=/^paul/] 获取用户名与 ^paul 匹配的用户元素。
{n}.User[id=1].name 获取 id 与 1 匹配的用户的姓名。

参数

ArrayAccess|array $data: 要从中提取的数据。
string $path: 要提取的路径。

ArrayAccess|array

链接

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

filter() ¶ public static

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

递归地过滤数据集。

参数

array $data: 要过滤的数组，或回调中的值
callable|null $callback 可选: 用于过滤数据的函数。默认为所有非空或零值。

array

链接

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

flatten() ¶ public static

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

将多维数组折叠成单维数组，使用分隔的数组路径作为每个数组元素的键，例如：[['Foo' => ['Bar' => 'Far']]] 变为 ['0.Foo.Bar' => 'Far']。

参数

array $data: 要扁平化的数组
string $separator 可选: 用于分隔路径中数组键元素的字符串，默认为 '.'

array

链接

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

format() ¶ public static

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

返回从 $data 中提取的一系列格式化值，使用 $format 作为格式，使用 $paths 作为要提取的值。

用法

$result = Hash::format($users, ['{n}.User.id', '{n}.User.name'], '%s : %s');

$format 字符串可以使用 vsprintf() 和 sprintf() 支持的任何格式选项。

参数

array $data: 从中提取数据的源数组
list<string> $paths: 包含一个或多个 Hash::extract()-style 键路径的数组
string $format: 将插入值的格式字符串，请参阅 sprintf()

list<string>|null

另请参阅

sprintf()
\Cake\Utility\Hash::extract()

链接

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

get() ¶ public static

get(ArrayAccess|array $data, list<string>|string|int|null $path, mixed $default = null): mixed

从 $data 中获取 $path 指定的单个值。不支持完整的点符号功能集，但对于简单的读取操作更快。

参数

ArrayAccess|array $data: 要操作的数据数组或实现 \ArrayAccess 接口的对象。
list<string>|string|int|null $path: 正在搜索的路径。点分隔字符串或路径段数组。
mixed $default 可选: 路径不存在时的返回值

混合

抛出

InvalidArgumentException

链接

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

insert() ¶ public static

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

使用给定的 $path 将 $values 插入数组。您可以使用 {n} 和 {s} 元素多次插入 $data。

参数

T $data: 要插入的数据。
string $path: 要插入的路径。
mixed $values optional: 要插入的值。

ArrayAccess|array

链接

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

map() ¶ public static

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

将回调映射到集合中的所有元素。可以提供路径来仅修改集合的切片。

参数

array $data: 要映射并从中提取数据的数据。
string $path: 用于映射的提取路径。
callable $function: 对每个提取的值调用的函数。

array

链接

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

maxDimensions() ¶ public static

maxDimensions(array $data): int

计算所有数组元素的维度。对于在混合数组中查找最大维度很有用。

参数

array $data: 要计算维度的数组

int

链接

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

merge() ¶ public static

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

此函数可以看作是 PHP 的 array_merge 和 array_merge_recursive 的混合体。

此方法与内置方法之间的区别在于，如果数组键包含另一个数组，则 Hash::merge() 将以递归方式运行（与 array_merge 不同）。但它不会对包含标量值的键进行递归操作（与 array_merge_recursive 不同）。

此函数将处理无限数量的参数，并将非数组参数类型转换为数组。

参数

array $data: 要合并的数组
mixed $merge: 要合并的数组。参数和所有尾随参数在合并时将被数组类型转换

array

链接

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

mergeDiff() ¶ public static

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

将 $data 和 $compare 之间的差异合并到 $data 上。

参数

array $data: 要附加到的数据。
array $compare: 要比较并附加到的数据。

array

链接

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

nest() ¶ public static

nest(array $data, array<string, string|null> $options = []): list<array>

接收扁平数组并返回嵌套数组。

选项

children 结果集中用于子项的键名。
idPath 标识每个条目的键的路径。应与 Hash::extract() 兼容。默认为 {n}.$alias.id
parentPath 标识每个条目父项的键的路径。应与 Hash::extract() 兼容。默认为 {n}.$alias.parent_id
root 想要的最顶层结果的 id。

参数

array $data: 要嵌套的数据。
array<string, string|null> $options 可选: 选项。

list<array>

抛出

InvalidArgumentException
提供无效数据时。

另请参阅

\Cake\Utility\Hash::extract()

链接

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

normalize() ¶ public static

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

规范化数组，并将其转换为标准格式。

参数

array $data: 要规范化的列表
bool $assoc 可选: 如果为 true，则 $data 将被转换为关联数组。
mixed $default 可选: 将顶层数字键转换为关联形式时使用的默认值。

array

链接

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

numeric() ¶ public static

numeric(array $data): bool

检查数组中的所有值是否都是数字。

参数

array $data: 要检查的数组。

bool

链接

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

reduce() ¶ public static

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

使用 $function 减少一组提取的值。

参数

array $data: 要减少的数据。
string $path: 从 $data 中提取的路径。
callable $function: 对每个提取的值调用的函数。

混合

链接

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

remove() ¶ public static

remove(T $data, string $path): ArrayAccess|array

从 $data 数组中删除与 $path 匹配的数据。您可以使用 {n} 和 {s} 从 $data 中删除多个元素。

参数

T $data: 要操作的数据
string $path: 要用于删除的路径表达式。

ArrayAccess|array

链接

https://book.cakephp.com.cn/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

根据任何值对数组进行排序，由 Set 兼容的路径确定。

排序方向

asc 或 \SORT_ASC 递增排序。
desc 或 \SORT_DESC 递减排序。

排序类型

regular 常规排序（不改变类型）
numeric 按数值比较
string 按字符串比较
locale 根据当前区域设置按字符串比较
natural 使用“自然排序”按字符串比较，以人性化方式排序，例如，将 foo10 排序到 foo2 之后。

要执行不区分大小写的排序，请将类型作为数组传递，如下所示

Hash::sort($data, 'some.attribute', 'asc', ['type' => 'regular', 'ignoreCase' => true]);

使用数组形式时，type 默认为 'regular'。ignoreCase 选项默认为 false。

参数

array $data: 要排序的数据数组
string $path: 与 Set 兼容的数组值路径
string|int $dir 可选: 参见上面的方向。默认为 'asc'。
array<string, mixed>|string $type 可选: 参见上面的方向类型。默认为 'regular'。

array

链接

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

命名空间

类 Hash

方法概述

_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

方法详情

_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

参数