Class yii\helpers\BaseArrayHelper

继承yii\helpers\BaseArrayHelper
子类yii\helpers\ArrayHelper
可用自版本2.0
源代码 https://github.com/yiisoft/yii2/blob/master/framework/helpers/BaseArrayHelper.php

BaseArrayHelper 为 yii\helpers\ArrayHelper 提供了具体的实现方法.

不要使用 BaseArrayHelper. 改用 yii\helpers\ArrayHelper.

公共方法

隐藏继承的方法

方法描述定义在
filter() 根据指定的规则过滤数组. yii\helpers\BaseArrayHelper
getColumn() 返回数组中指定列的值. yii\helpers\BaseArrayHelper
getValue() 检索具有给定的键或属性名称的数组元素或对象属性的值. yii\helpers\BaseArrayHelper
htmlDecode() 将 HTML 实体解码为字符串数组中的相应字符. yii\helpers\BaseArrayHelper
htmlEncode() 将字符串数组中的特殊字符编码为 HTML 实体. yii\helpers\BaseArrayHelper
index() 根据指定的键名对数组进行索引和/或分组. yii\helpers\BaseArrayHelper
isAssociative() 检查给定的数组是否为关联数组. yii\helpers\BaseArrayHelper
isIn() 检查数组或 Traversable 是否包含元素. yii\helpers\BaseArrayHelper
isIndexed() 检查给定的数组是否为索引数组. yii\helpers\BaseArrayHelper
isSubset() 检查数组或 Traversable 是否是另一个数组或 Traversable 的子集. yii\helpers\BaseArrayHelper
isTraversable() 检查变量是数组还是 Traversable. yii\helpers\BaseArrayHelper
keyExists() 检查给定的数组是否包含指定的键名. yii\helpers\BaseArrayHelper
map() 从多维数组或对象数组中构建映射表(键值对). yii\helpers\BaseArrayHelper
merge() 递归合并两个或更多数组. yii\helpers\BaseArrayHelper
multisort() 通过一个或多个键名对对象数组或数组(具有相同结构)进行排序. yii\helpers\BaseArrayHelper
remove() 从数组中删除键并返回值. 如果数组中不存在该键, 则将返回默认值. yii\helpers\BaseArrayHelper
removeValue() 从数组中删除具有匹配值的项目, 并返回已删除的项目. yii\helpers\BaseArrayHelper
setValue() 将值写入指定键路径的关联数组中. yii\helpers\BaseArrayHelper
toArray() 将对象或对象数组转换为数组. yii\helpers\BaseArrayHelper

方法详情

filter() public static 方法 (可用自版本: 2.0.9)

根据指定的规则过滤数组.

例如:

$array = [
    'A' => [1, 2],
    'B' => [
        'C' => 1,
        'D' => 2,
    ],
    'E' => 1,
];

$result = \yii\helpers\ArrayHelper::filter($array, ['A']);
// $result 将是:
// [
//     'A' => [1, 2],
// ]

$result = \yii\helpers\ArrayHelper::filter($array, ['A', 'B.C']);
// $result 将是:
// [
//     'A' => [1, 2],
//     'B' => ['C' => 1],
// ]

$result = \yii\helpers\ArrayHelper::filter($array, ['B', '!B.C']);
// $result 将是:
// [
//     'B' => ['D' => 2],
// ]
public static array filter ( $array, $filters )
$array array

源数组.

$filters array

定义应从结果中保留或删除的数组键的规则. 每条规则都是:

  • var: $array['var']将留在结果中.
  • var.key: $array['var']['key']将留在结果中.
  • !var.key: $array['var']['key']将从结果中删除.
return array

过滤后的数组.

getColumn() public static 方法

返回数组中指定列的值.

输入数组应该是多维数组或对象数组.

例如,

$array = [
    ['id' => '123', 'data' => 'abc'],
    ['id' => '345', 'data' => 'def'],
];
$result = ArrayHelper::getColumn($array, 'id');
// the result is: ['123', '345']

// 使用匿名函数
$result = ArrayHelper::getColumn($array, function ($element) {
    return $element['id'];
});
public static array getColumn ( $array, $name, $keepKeys true )
$array array
$name integer|string|Closure
$keepKeys boolean

是否保留数组的键, 如果为false, 则结果数组将使用整数重新索引.

return array

列值的列表.

getValue() public static 方法

检索具有给定的键或属性名称的数组元素或对象属性的值.

如果该数组或对象中不存在该键, 则将返回默认值. 从对象中获取值时不使用.

键名可以用点格式指定, 以检索子数组的值或嵌入对象的属性. 特别是, 如果键名是x.y.z, 那么返回的值将是$array['x']['y']['z']$array->x->y->z(如果$array是一个对象). 如果$array['x']$array->x既不是数组也不是对象, 则返回默认值.

Note: 如果数组已经有一个元素x.y.z, 那么它的值将被返回而不是遍历子数组. 所以最好指定一个键名称的数组, 如['x', 'y', 'z'].

以下是一些使用示例:

// 使用数组:
$username = \yii\helpers\ArrayHelper::getValue($_POST, 'username');
// 使用对象:
$username = \yii\helpers\ArrayHelper::getValue($user, 'username');
// 使用匿名函数:
$fullName = \yii\helpers\ArrayHelper::getValue($user, function ($user, $defaultValue) {
    return $user->firstName . ' ' . $user->lastName;
});
// 使用点格式来检索嵌入对象的属性:
$street = \yii\helpers\ArrayHelper::getValue($users, 'address.street');
// 使用一组键来检索值:
$value = \yii\helpers\ArrayHelper::getValue($versions, ['1.0', 'date']);
public static mixed getValue ( $array, $key, $default null )
$array array|object

要从中提取值的数组或对象.

$key string|Closure|array

数组元素的键名, 对象的键或属性名的数组; 或返回值的匿名函数, 匿名函数的签名应是:function($array, $defaultValue). 自版本 2.0.4 起开始, 可以传递一组键.

$default mixed

如果指定的数组键不存在, 则返回的默认值. 从对象中获取值时不使用.

return mixed

找到的元素的值, 否则为默认值.

htmlDecode() public static 方法

将 HTML 实体解码为字符串数组中的相应字符.

默认情况下, 只解码数组值. 如果某个值是一个数组, 该方法也会以递归的方式对其进行解码. 仅解码字符串值.

参见 https://secure.php.net/manual/en/function.htmlspecialchars-decode.php.

public static array htmlDecode ( $data, $valuesOnly true )
$data array

要解码的数据.

$valuesOnly boolean

是否仅解码数组值. 如果为false, 则数组的键和值都将被解码.

return array

解码后的数据.

htmlEncode() public static 方法

将字符串数组中的特殊字符编码为 HTML 实体.

默认情况下, 只编码数组值. 如果某个值是一个数组, 该方法也会以递归的方式对其进行编码. 仅编码字符串值.

参见 https://secure.php.net/manual/en/function.htmlspecialchars.php.

public static array htmlEncode ( $data, $valuesOnly true, $charset null )
$data array

要编码的数据.

$valuesOnly boolean

是否仅编码数组值. 如果为false, 则数组的键和值都将被编码.

$charset string

数据正在使用的字符集. 如果未设置, 将使用 yii\base\Application::$charset.

return array

编码后的数据.

index() public static 方法

根据指定的键名对数组进行索引和/或分组.

输入应该是多维数组或对象数组.

$key可以是子数组的键名称, 对象的属性名称, 也可以是必须返回将用作键的值的匿名函数.

$groups是一组键名, 它将用于根据指定的键名将输入数组分组到一个或多个子数组中.

如果$key被指定为null, 或者除了未指定$groups之外, 与该键相对应的元素的值为null, 则该元素将被丢弃.

例如:

$array = [
    ['id' => '123', 'data' => 'abc', 'device' => 'laptop'],
    ['id' => '345', 'data' => 'def', 'device' => 'tablet'],
    ['id' => '345', 'data' => 'hgi', 'device' => 'smartphone'],
];
$result = ArrayHelper::index($array, 'id');

结果将是一个关联数组, 其中键名是id属性的值:

[
    '123' => ['id' => '123', 'data' => 'abc', 'device' => 'laptop'],
    '345' => ['id' => '345', 'data' => 'hgi', 'device' => 'smartphone']
    // 由于具有相同的 id, 原始数组的第二个元素将被最后一个元素覆盖
]

匿名函数也可以在分组数组中使用:

$result = ArrayHelper::index($array, function ($element) {
    return $element['id'];
});

传递id作为第三个参数将按id分配给$array:

$result = ArrayHelper::index($array, null, 'id');

结果将是一个多维数组, 在第一级由id分组, 在第二级由device分组, 在第三级由data索引:

[
    '123' => [
        ['id' => '123', 'data' => 'abc', 'device' => 'laptop']
    ],
    '345' => [ // 所有具有此索引的元素都存在于结果数组中
        ['id' => '345', 'data' => 'def', 'device' => 'tablet'],
        ['id' => '345', 'data' => 'hgi', 'device' => 'smartphone'],
    ]
]

匿名函数也可以在分组键数组中使用:

$result = ArrayHelper::index($array, 'data', [function ($element) {
    return $element['id'];
}, 'device']);

结果将是一个多维数组, 在第一级由id分组, 在第二级由device分组, 在第三级由data索引:

[
    '123' => [
        'laptop' => [
            'abc' => ['id' => '123', 'data' => 'abc', 'device' => 'laptop']
        ]
    ],
    '345' => [
        'tablet' => [
            'def' => ['id' => '345', 'data' => 'def', 'device' => 'tablet']
        ],
        'smartphone' => [
            'hgi' => ['id' => '345', 'data' => 'hgi', 'device' => 'smartphone']
        ]
    ]
]
public static array index ( $array, $key, $groups = [] )
$array array

需要进行索引或分组的数组.

$key string|Closure|null

列名或匿名函数的结果将用于索引数组.

$groups string|string[]|Closure[]|null

键数组, 用于通过一个或多个键对输入数组进行分组. 如果$key属性或其特定元素的值为null, 且$groups未定义, 则该数组元素将被丢弃. 否则, 如果指定了$groups, 则数组元素将被添加到结果数组中而不包含任何键. 该参数自版本 2.0.8 起可用.

return array

索引和/或分组的数组.

isAssociative() public static 方法

检查给定的数组是否为关联数组.

如果数组的所有键都是字符串, 则是关联数组. 如果$allStringsfalse, 那么如果数组至少有一个键是字符串, 则数组将被视为关联数组.

Note: 空数组不会被认为是关联数组.

public static boolean isAssociative ( $array, $allStrings true )
$array array

要检查的数组.

$allStrings boolean

数组键是否必须都是字符串才能将数组视为关联数组.

return boolean

数组是否是关联数组.

isIn() public static 方法 (可用自版本: 2.0.7)

检查数组或 Traversable 是否包含元素.

该方法与 PHP 函数 in_array() 相同, 但也适用于实现了 Traversable 接口的对象.

参见 https://secure.php.net/manual/en/function.in-array.php.

public static boolean isIn ( $needle, $haystack, $strict false )
$needle mixed

要查找的键值.

$haystack array|Traversable

要搜索的数组.

$strict boolean

是否启用严格比较(===).

return boolean

如果在$haystack中找到$needle, 则返回true, 否则返回false.

throws yii\base\InvalidArgumentException

如果$haystack既不可遍历也不是数组.

isIndexed() public static 方法

检查给定的数组是否为索引数组.

如果数组的所有键都是整数, 则是索引数组. 如果$consecutivetrue, 则数组的键必须是从0开始的连续序列.

Note: 空数组将被视为索引数组.

public static boolean isIndexed ( $array, $consecutive false )
$array array

要检查的数组.

$consecutive boolean

数组的键是否必须是连续的序列才能将数组视为索引数组.

return boolean

数组是否是索引数组.

isSubset() public static 方法 (可用自版本: 2.0.7)

检查数组或 Traversable 是否是另一个数组或 Traversable 的子集.

如果$needles中的所有元素都包含在$haystack中, 则此方法将返回true. 如果至少缺少一个元素, 则返回false.

public static boolean isSubset ( $needles, $haystack, $strict false )
$needles array|Traversable

必须全部在$haystack中的值.

$haystack array|Traversable

要搜索的值集.

$strict boolean

是否启用严格比较(===).

return boolean

如果$needles$haystack的子集, 则返回true, 否则返回false.

throws yii\base\InvalidArgumentException

如果$haystack$needles既不可遍历也不是数组.

isTraversable() public static 方法 (可用自版本: 2.0.8)

检查变量是数组还是 Traversable.

该方法与 PHP 函数 is_array() 相同, 但也适用于实现了 Traversable 接口的对象.

参见 https://secure.php.net/manual/en/function.is-array.php.

public static boolean isTraversable ( $var )
$var mixed

要检查的变量.

return boolean

$var是否是数组.

keyExists() public static 方法

检查给定的数组是否包含指定的键名.

该方法通过支持不区分大小写的键名比较来增强array_key_exists()功能.

public static boolean keyExists ( $key, $array, $caseSensitive true )
$key string

要检查的键名.

$array array

被检查的数组.

$caseSensitive boolean

键名比较是否应区分大小写.

return boolean

数组是否包含指定的键名.

map() public static 方法

从多维数组或对象数组中构建映射表(键值对).

$from$to参数分别指定了用于构建映射表的键名和属性名. 根据需要, 可以使用分组字段$group进一步对映射表进行分组.

例如,

$array = [
    ['id' => '123', 'name' => 'aaa', 'class' => 'x'],
    ['id' => '124', 'name' => 'bbb', 'class' => 'x'],
    ['id' => '345', 'name' => 'ccc', 'class' => 'y'],
];

$result = ArrayHelper::map($array, 'id', 'name');
// 结果是:
// [
//     '123' => 'aaa',
//     '124' => 'bbb',
//     '345' => 'ccc',
// ]

$result = ArrayHelper::map($array, 'id', 'name', 'class');
// 结果是:
// [
//     'x' => [
//         '123' => 'aaa',
//         '124' => 'bbb',
//     ],
//     'y' => [
//         '345' => 'ccc',
//     ],
// ]
public static array map ( $array, $from, $to, $group null )
$array array
$from string|Closure
$to string|Closure
$group string|Closure
merge() public static 方法

递归合并两个或更多数组.

如果每个数组都有一个具有相同字符串键值的元素, 则后者将覆盖前者(与array_merge_recursive不同).

如果两个数组都有一个数组类型的元素并且具有相同的键名, 则将执行递归合并.

对于整数型键名的元素, 后一个数组中的元素将被附加到前一个数组.

您可以使用 yii\helpers\UnsetArrayValue 对象来取消前一个数组的值, 或使用 yii\helpers\ReplaceArrayValue 对象强制替换先前的值而不是递归合并.

public static array merge ( $a, $b )
$a array

被合并的数组.

$b array

合并的数组. 您可以通过第三个, 第四个参数等指定其它数组.

return array

合并的结果数组(不改变原始数组).

multisort() public static 方法

通过一个或多个键名对对象数组或数组(具有相同结构)进行排序.

public static void multisort ( &$array, $key, $direction SORT_ASC, $sortFlag SORT_REGULAR )
$array array

要排序的数组. 调用此方法后, 该数组将被修改.

$key string|Closure|array

要排序的键. 这是指子数组元素的键名称, 对象的属性名称或返回值以进行比较的匿名函数. 匿名函数的签名应该是function($item). 要按多个键名进行排序, 请在此处提供一组键名.

$direction integer|array

排序方向. 它可以是SORT_ASCSORT_DESC. 使用具有不同排序方向的多个键进行排序时, 请使用排序方向数组.

$sortFlag integer|array

PHP 的排序标识, 有效值包括: SORT_REGULAR, SORT_NUMERIC, SORT_STRING, SORT_LOCALE_STRING, SORT_NATURALSORT_FLAG_CASE. 有关更多详细信息, 请参阅 PHP 手册. 使用具有不同排序标识的多个键名进行排序时, 请使用排序标志数组.

throws yii\base\InvalidArgumentException

如果 $direction$sortFlag参数的元素数量与$key的元素数不符.

remove() public static 方法

从数组中删除键并返回值. 如果数组中不存在该键, 则将返回默认值.

例如,

// $array = ['type' => 'A', 'options' => [1, 2]];
// working with array
$type = \yii\helpers\ArrayHelper::remove($array, 'type');
// $array content
// $array = ['options' => [1, 2]];
public static mixed|null remove ( &$array, $key, $default null )
$array array

要从中提取值的数组.

$key string

数组元素的键名.

$default mixed

如果指定的键不存在时, 返回的默认值.

return mixed|null

找到的元素的值, 否则为默认值.

removeValue() public static 方法 (可用自版本: 2.0.11)

从数组中删除具有匹配值的项目, 并返回已删除的项目.

例如,

$array = ['Bob' => 'Dylan', 'Michael' => 'Jackson', 'Mick' => 'Jagger', 'Janet' => 'Jackson'];
$removed = \yii\helpers\ArrayHelper::removeValue($array, 'Jackson');
// result:
// $array = ['Bob' => 'Dylan', 'Mick' => 'Jagger'];
// $removed = ['Michael' => 'Jackson', 'Janet' => 'Jackson'];
public static array removeValue ( &$array, $value )
$array array

要从中查找值的数组.

$value string

要从数组中删除的值.

return array

从数组中删除的项目.

setValue() public static 方法 (可用自版本: 2.0.13)

将值写入指定键路径的关联数组中.

如果还没有这样的键路径, 它将以递归方式创建. 如果键已存在, 它将被覆盖.

 $array = [
     'key' => [
         'in' => [
             'val1',
             'key' => 'val'
         ]
     ]
 ];

ArrayHelper::setValue($array, 'key.in.0', ['arr' => 'val']);的结果如下:

 [
     'key' => [
         'in' => [
             ['arr' => 'val'],
             'key' => 'val'
         ]
     ]
 ]

ArrayHelper::setValue($array, 'key.in', ['arr' => 'val']);或者ArrayHelper::setValue($array, ['key', 'in'], ['arr' => 'val']);的结果如下:

 [
     'key' => [
         'in' => [
             'arr' => 'val'
         ]
     ]
 ]
public static void setValue ( &$array, $path, $value )
$array array

要写入值的数组.

$path string|array|null

你想把值写入$array的路径. 路径可以用一个字符串来描述, 每个键都应该用点.分割. 如果路径为null, 那么你也可以将路径描述为一个键数组, 然后$array将被赋值$value.

$value mixed

要写入的值.

toArray() public static 方法

将对象或对象数组转换为数组.

public static array toArray ( $object, $properties = [], $recursive true )
$object object|array|string

要转换为数组的对象.

$properties array

从对象类名称到需要放入结果数组的属性的映射. 为每个类指定的属性是以下格式的数组:

[
    'app\models\Post' => [
        'id',
        'title',
        // 结果数组中的键名称 => 属性名称
        'createTime' => 'created_at',
        // 结果数组中的键名称 => 匿名函数
        'length' => function ($post) {
            return strlen($post->content);
        },
    ],
]

ArrayHelper::toArray($post, $properties)的结果可能如下所示:

[
    'id' => 123,
    'title' => 'test',
    'createTime' => '2013-01-01 12:00AM',
    'length' => 301,
]
$recursive boolean

是否以递归方式将对象的属性转换为数组.

return array

对象的数组表示.