Deprecated
This library isn't in active development. Various other collection libraries provide most functionality that we need out of the box., (*1)
Bug fixes only., (*2)
UtilityBelt
, (*3)
Every time we start a new php project that requires even a small amount of data
wrangling, we find ourselves re-writing the same helper functions over and over again., (*4)
This package provides some key functions that make it easier to perform
common tasks like:
* finding and filtering values in collections of arrays
* grouping values in collections by properties
* extracting values from deeply nested associative arrays
* recursive array mapping
* determining if an array is associative
* and more..., (*5)
These functions are all provided without pulling in any heavy framework
dependencies or third party packages., (*6)
Installation
Install the latest version with:, (*7)
$ composer require rexlabs/utility-belt
CollectionUtility
filterWhere / filterWhereNot
(array $items, array $properties), (*8)
Some extremely common functionality involves filtering collections (arrays of rows)
based on a property list. The code required for this via array_filter tends to become
fairly bloated and makes the purpose of the underlying code harder to understand. These
functions provide a simpler way to perform these kinds of filters., (*9)
All comparisons below can be run as case insensitive or strict checks., (*10)
$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), (*11)
Similar to the filter methods but returns the first matching result and optionally
the key where it was found., (*12)
groupByProperty / keyByProperty
(array $array, $key), (*13)
Re-organises rows in a collection under the values of one or more properties., (*14)
The difference between the two methods is that key by property allows for only
a single row per property in the result while grouping will return an array
of collections., (*15)
$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), (*16)
Sort a collection using a property or nested property, (*17)
$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), (*18)
Remove (or nullify) all keys in each collection item except for those specified in the keys arg, (*19)
$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), (*20)
Remove (or nullify) any keys provided in the $keys argument in each collection item., (*21)
$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), (*22)
Get a random item from an array, (*23)
shuffle
(array $array), (*24)
Shuffle an array and return the result, (*25)
ArrayUtility
dotRead
(array $array, $property, $default_value=null), (*26)
$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), (*27)
Original array:, (*28)
$array = [
"a"=>[
"very"=>[
"deep"=>[
"hole"=>"with a prize at the bottom"
]
]
],
"i"=>[
"like"=>"candy"
]
]
Return a new array containing the updated property:, (*29)
$array = ArrayUtility::dotWrite($array, "a.very.deep.hole", "no prize!");
$array - ArrayUtility::dotWrite($array, "i.like", ["carrots","broccoli"]);
Array is now:, (*30)
$array = [
"a"=>[
"very"=>[
"deep"=>[
"hole"=>"no prize!"
]
]
],
"i"=>[
"like"=>["carrots","broccoli"]
]
]
Set new properties:, (*31)
$array = ArrayUtility::dotWrite($array, "a.very.shallow.hole", "that may contain a prize!");
$array = ArrayUtility::dotWrite($array, "i.also.like", "blue skies");
Array is now:, (*32)
$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), (*33)
This method is similar to dotWrite() except the array is passed by reference so that property changes directly
mutate the given array., (*34)
Original array:, (*35)
$array = [
"a"=>[
"very"=>[
"deep"=>[
"hole"=>"with a prize at the bottom"
]
]
],
"i"=>[
"like"=>"candy"
]
]
Mutate the array with the updated property:, (*36)
ArrayUtility::dotMutate($array, "a.very.deep.hole", "no prize!");
ArrayUtility::dotMutate($array, "i.like", ["carrots","broccoli"]);
Array is now:, (*37)
$array = [
"a"=>[
"very"=>[
"deep"=>[
"hole"=>"no prize!"
]
]
],
"i"=>[
"like"=>["carrots","broccoli"]
]
]
Set new properties:, (*38)
ArrayUtility::dotMutate($array, "a.very.shallow.hole", "that may contain a prize!");
ArrayUtility::dotMutate($array, "i.also.like", "blue skies");
Array is now:, (*39)
$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), (*40)
$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), (*41)
Quick test to determine whether an array is associative or not., (*42)
ArrayUtility::isAssoc(["a"=>1,"b"=>2])
true
ArrayUtility::isAssoc(["a","b"])
false
keepKeys
(array $array, array $keys, ArrayUtility::REMOVAL_ACTION_DELETE), (*43)
Same as CollectionUtility::keepKeys but operates on a basic array instead of a collection of arrays., (*44)
removeKeys
(array $array, array $keys, ArrayUtility::REMOVAL_ACTION_DELETE), (*45)
Same as CollectionUtility::removeKeys but operates on a basic array instead of a collection of arrays., (*46)
mapRecursive
(array $array, callable $callback, $map_arrays = false), (*47)
Like array walk recursive but doesn't mutate the array. Also, callback receives three arguments: $value, $key, $array, (*48)
map
(array $array, callable $callback), (*49)
Like array_map but the callback receives three arguments: $value, $key, $array, (*50)
first
(array $array), (*51)
Returns the first element from an array. More useful than reset() because it can handle the result of a function., (*52)
last
(array $array), (*53)
Returns the last element from an array. More useful than end() because it can handle the result of a function., (*54)
firstKey
(array $array), (*55)
Returns the key of the first element in an array., (*56)
lastKey
(array $array), (*57)
Returns the key of the last element in an array., (*58)
Install
Install UtilityBelt using Composer., (*59)
$ composer require rexlabs/utility-belt
Testing
UtilityBelt has a PHPUnit test suite. To run the tests, run the following command from the project folder., (*60)
bash
$ composer test, (*61)
Credits
License
The MIT License (MIT). Please see LICENSE for more information., (*62)
Wallogit.com
