README

更新！UtilityBelt 已迁移至 Rex Labs

• GitHub 仓库
• Composer 包

请更新您的项目以使用新的包，因为它将不再在 bkvfoundry 仓库下维护

UtilityBelt

每次我们开始一个新的PHP项目，即使只需要处理一点数据，我们都会发现自己一遍又一遍地重写相同的辅助函数。

此包提供了一些关键函数，可以更轻松地执行常见任务，如

• 在数组的集合中查找和过滤值
• 按属性分组集合中的值
• 从深层嵌套的关联数组中提取值
• 递归数组映射
• 确定数组是否为关联数组
• 等等...

这些函数都是提供，而不需要引入任何重型框架依赖项或第三方包。

安装

使用以下命令安装最新版本

$ composer require bkvfoundry/utility-belt

CollectionUtility

filterWhere / filterWhereNot

(array $items, array $properties)

一些极其常见的功能涉及根据属性列表过滤集合（行数组）。使用 array_filter 实现此功能所需的代码往往相当冗长，使得底层代码的目的更难理解。这些函数提供了执行此类过滤器的一种更简单的方式。

以下所有比较均可作为不区分大小写的比较或严格比较运行。

$items = [
    [
        "name"=>"john",
        "age"=>18
    ],
    [
        "name"=>"mary",
        "age"=>19
    ],
    [
        "name"=>"william",
        "age"=>18,
        "dog"=>[
            "name"=>"betty"
        ]
    ]
];

CollectionUtility::filterWhere($items,["age"=>18])
// [["name"=>"john",...], ["name"=>"william",...]];

CollectionUtility::filterWhereNot($items,["age"=>18])
// [["name"=>"mary",...]]

CollectionUtility::filterWhere($items,["dog.name"=>"betty"])
// [["name"=>"william",...]]

CollectionUtility::filterWhere($items,[["dog.name"=>"betty"],["name"=>"john"]]);
// [["name"=>"william",...], ["name"=>"john"]]

findWhere / findWhereNot

(array $items, array $properties)

类似于过滤方法，但返回第一个匹配结果，并可选地返回找到的位置。

groupByProperty / keyByProperty

(array $array, $key)

根据一个或多个属性值重新组织集合中的行。

这两种方法的区别在于，按属性分组允许每个属性只有一个行结果，而分组将返回一个集合数组。

$items = [
    ["name"=>"john","dog"=>["name"=>"william"]],
    ["name"=>"frank","dog"=>["name"=>"william"]],
    ["name"=>"dodd","dog"=>["name"=>"bruce"]],
];

CollectionUtility::keyByProperty($items,"dog.name")
[
   "william"=>["name"=>"frank","dog"=>["name"=>"william"]],
   "bruce"=>["name"=>"dodd","dog"=>["name"=>"bruce"]],
]

CollectionUtility::keyByProperty($items,["name","dog.name"])
[
    "john.william"=>["name"=>"john","dog"=>["name"=>"william"]],
    "frank.william"=>["name"=>"frank","dog"=>["name"=>"william"]],
    "dodd.bruce"=>["name"=>"dodd","dog"=>["name"=>"bruce"]],
]

CollectionUtility::groupByProperty($items,"dog.name")
[
    "william"=>[
        ["name"=>"john","dog"=>["name"=>"william"]],
        ["name"=>"frank","dog"=>["name"=>"william"]],
    ],
    "bruce"=>[
        ["name"=>"dodd","dog"=>["name"=>"bruce"]],
    ]
]

sort / asort

(array $array, $property, $sort_direction = self::SORT_DIRECTION_ASCENDING, $sort_flags=SORT_REGULAR)

使用属性或嵌套属性对集合进行排序

$items = [
    ["string"=>"a", "nested"=>["number"=>1]],
    ["string"=>"d", "nested"=>["number"=>3]],
    ["string"=>"c", "nested"=>["number"=>3]],
    ["string"=>"b", "nested"=>["number"=>2]],
];

CollectionUtility::sort($items, "nested.number", CollectionUtility::SORT_DIRECTION_DESCENDING, SORT_NUMERIC);
[
    ["string"=>"c", "nested"=>["number"=>3]],
    ["string"=>"d", "nested"=>["number"=>3]],
    ["string"=>"b", "nested"=>["number"=>2]],
    ["string"=>"a", "nested"=>["number"=>1]]
]

keepKeys

(array $array, array $keys, $removal_action = CollectionUtility::REMOVAL_ACTION_DELETE)

移除（或使为null）每个集合项中除了在键参数中指定的键之外的所有键

$items = [
    ["animal"=>"dog","name"=>"John","weather"=>"mild"],
    ["animal"=>"cat","name"=>"William"]
];

CollectionUtility::keepKeys($items, ["animal","weather"], CollectionUtility::REMOVAL_ACTION_DELETE);
[
    ["animal"=>"dog", "weather"=>"mild"],
    ["animal"=>"cat"]
]

CollectionUtility::keepKeys($items, ["animal","weather"], CollectionUtility::REMOVAL_ACTION_NULLIFY);
[
    ["animal"=>"dog", "name"=>null, ""weather"=>"mild"],
    ["animal"=>"cat", "name"=>null]
]

removeKeys

(array $array, array $keys, $removal_action = CollectionUtility::REMOVAL_ACTION_DELETE)

在集合的每个项中移除（或使为null）在 $keys 参数中提供的任何键。

$items = [
    ["animal"=>"dog","name"=>"John","weather"=>"mild"],
    ["animal"=>"cat","name"=>"William"]
];

CollectionUtility::removeKeys($items, ["animal","weather"], CollectionUtility::REMOVAL_ACTION_DELETE);
[
    ["name"=>"John"],
    ["name"=>"William"]
]

random

(array $array)

从数组中获取一个随机项

shuffle

(array $array)

打乱数组并返回结果

ArrayUtility

dotRead

(array $array, $property, $default_value=null)

$array = [
    "a"=>[
        "very"=>[
            "deep"=>[
                "hole"=>"with a prize at the bottom"
            ]
        ]
    ]
]

ArrayUtility::dotRead($array, "a.very.shallow.hole", "no prize!")
"no prize!"

ArrayUtility::dotRead($array, "a.very.deep.hole")
"with a prize at the bottom"

dotWrite

(array $array, $property, $value)

原始数组

$array = [
    "a"=>[
        "very"=>[
            "deep"=>[
                "hole"=>"with a prize at the bottom"
            ]
        ]
    ],
    "i"=>[
        "like"=>"candy"
    ]
]

返回一个包含更新属性的新数组

$array = ArrayUtility::dotWrite($array, "a.very.deep.hole", "no prize!");
$array - ArrayUtility::dotWrite($array, "i.like", ["carrots","broccoli"]);

数组现在是

$array = [
    "a"=>[
        "very"=>[
            "deep"=>[
                "hole"=>"no prize!"
            ]
        ]
    ],
    "i"=>[
        "like"=>["carrots","broccoli"]
    ]
]

设置新属性

$array = ArrayUtility::dotWrite($array, "a.very.shallow.hole", "that may contain a prize!");
$array = ArrayUtility::dotWrite($array, "i.also.like", "blue skies");

数组现在是

$array = [
    "a"=>[
        "very"=>[
            "deep"=>[
                "hole"=>"no prize!"
            ]
        ]
    ],
    "a"=>[
        "very"=>[
            "shallow"=>[
                "hole"=>"that may contain a prize!"
            ]
        ]
    ],
    "i"=>[
        "like"=>["carrots","broccoli"]
        "also"=>[
            "like"=>"blue skies"
        ]
    ]
]

dotMutate

(array $array, $property, $value)

此方法类似于 dotWrite()，但数组是按引用传递的，因此属性更改会直接修改给定的数组。

原始数组

$array = [
    "a"=>[
        "very"=>[
            "deep"=>[
                "hole"=>"with a prize at the bottom"
            ]
        ]
    ],
    "i"=>[
        "like"=>"candy"
    ]
]

使用更新属性修改数组

ArrayUtility::dotMutate($array, "a.very.deep.hole", "no prize!");
ArrayUtility::dotMutate($array, "i.like", ["carrots","broccoli"]);

数组现在是

$array = [
    "a"=>[
        "very"=>[
            "deep"=>[
                "hole"=>"no prize!"
            ]
        ]
    ],
    "i"=>[
        "like"=>["carrots","broccoli"]
    ]
]

设置新属性

ArrayUtility::dotMutate($array, "a.very.shallow.hole", "that may contain a prize!");
ArrayUtility::dotMutate($array, "i.also.like", "blue skies");

数组现在是

$array = [
    "a"=>[
        "very"=>[
            "deep"=>[
                "hole"=>"no prize!"
            ]
        ]
    ],
    "a"=>[
        "very"=>[
            "shallow"=>[
                "hole"=>"that may contain a prize!"
            ]
        ]
    ],
    "i"=>[
        "like"=>["carrots","broccoli"]
        "also"=>[
            "like"=>"blue skies"
        ]
    ]
]

flatten / inflate

(array $array)

$items = [
    "a"=>[
        "name"=>"jimmy",
        "fruits"=>["apple","banana"]
    ],
    "b"=>[
        "name"=>"william",
        "age"=>18,
        "dog"=>[
            "name"=>"betty"
        ]
    ]
]

ArrayUtility::flatten($items);
[
    "a.name"=>"jimmy",
    "a.fruits"=>["apple","banana"], //by default these are not flattened
    "b.name"=>"william",
    "b.age"=>18,
    "b.dog.name"=>"betty"
]

ArrayUtility::inflate($flattenedArray);
[
    "a"=>[
        "name"=>"jimmy",
        "fruits"=>["apple","banana"]
    ],
    "b"=>[
        "name"=>"william",
        "age"=>18,
        "dog"=>[
            "name"=>"betty"
        ]
    ]
]

isAssoc

(array $array)

快速测试以确定数组是否为关联数组。

ArrayUtility::isAssoc(["a"=>1,"b"=>2])
true

ArrayUtility::isAssoc(["a","b"])
false

keepKeys

(array $array, array $keys, ArrayUtility::REMOVAL_ACTION_DELETE)

与 CollectionUtility::keepKeys 相同，但操作的是基本数组而不是数组集合。

removeKeys

(array $array, array $keys, ArrayUtility::REMOVAL_ACTION_DELETE)

与 CollectionUtility::removeKeys 相同，但操作的是基本数组而不是数组集合。

mapRecursive

(数组 $array, 可调用 $callback, $map_arrays = false)

类似于递归的 array_walk，但不会修改数组。同时，回调函数接收三个参数：$value, $key, $array

map

(数组 $array, 可调用 $callback)

类似于 array_map，但回调函数接收三个参数：$value, $key, $array

first

(array $array)

从数组中返回第一个元素。比 reset() 更有用，因为它可以处理函数的结果。

last

(array $array)

从数组中返回最后一个元素。比 end() 更有用，因为它可以处理函数的结果。

firstKey

(array $array)

返回数组中第一个元素的键。

lastKey

(array $array)

返回数组中最后一个元素的键。

安装

使用 Composer 安装 UtilityBelt。

$ composer require bkvfoundry/utility-belt

测试

UtilityBelt 有一个 PHPUnit 测试套件。要运行测试，请从项目文件夹中运行以下命令。

$ composer test

鸣谢

• Alex Babkov
• 所有贡献者

许可证

MIT 许可证 (MIT)。有关更多信息，请参阅 LICENSE。