rexlabs / utility-belt
A set of helpful utilities for working with data, collections (arrays of arrays) and arrays in php
Requires
- php: >=7.4 <8.3
Requires (Dev)
- phpunit/phpunit: ^9
This package is auto-updated.
Last update: 2024-10-19 16:28:56 UTC
README
This library isn't in active development. Various other collection libraries provide most functionality that we need out of the box.
Bug fixes only.
UtilityBelt
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.
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...
These functions are all provided without pulling in any heavy framework dependencies or third party packages.
Installation
Install the latest version with:
$ composer require rexlabs/utility-belt
CollectionUtility
filterWhere / filterWhereNot
(array $items, array $properties)
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.
All comparisons below can be run as case insensitive or strict checks.
$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)
Similar to the filter methods but returns the first matching result and optionally the key where it was found.
groupByProperty / keyByProperty
(array $array, $key)
Re-organises rows in a collection under the values of one or more properties.
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.
$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)
Sort a collection using a property or nested property
$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)
Remove (or nullify) all keys in each collection item except for those specified in the keys arg
$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)
Remove (or nullify) any keys provided in the $keys argument in each collection item.
$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)
Get a random item from an array
shuffle
(array $array)
Shuffle an array and return the result
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)
Original array:
$array = [ "a"=>[ "very"=>[ "deep"=>[ "hole"=>"with a prize at the bottom" ] ] ], "i"=>[ "like"=>"candy" ] ]
Return a new array containing the updated property:
$array = ArrayUtility::dotWrite($array, "a.very.deep.hole", "no prize!"); $array - ArrayUtility::dotWrite($array, "i.like", ["carrots","broccoli"]);
Array is now:
$array = [ "a"=>[ "very"=>[ "deep"=>[ "hole"=>"no prize!" ] ] ], "i"=>[ "like"=>["carrots","broccoli"] ] ]
Set new properties:
$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:
$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)
This method is similar to dotWrite() except the array is passed by reference so that property changes directly
mutate the given array.
Original array:
$array = [ "a"=>[ "very"=>[ "deep"=>[ "hole"=>"with a prize at the bottom" ] ] ], "i"=>[ "like"=>"candy" ] ]
Mutate the array with the updated property:
ArrayUtility::dotMutate($array, "a.very.deep.hole", "no prize!"); ArrayUtility::dotMutate($array, "i.like", ["carrots","broccoli"]);
Array is now:
$array = [ "a"=>[ "very"=>[ "deep"=>[ "hole"=>"no prize!" ] ] ], "i"=>[ "like"=>["carrots","broccoli"] ] ]
Set new properties:
ArrayUtility::dotMutate($array, "a.very.shallow.hole", "that may contain a prize!"); ArrayUtility::dotMutate($array, "i.also.like", "blue skies");
Array is now:
$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)
Quick test to determine whether an array is associative or not.
ArrayUtility::isAssoc(["a"=>1,"b"=>2])
true
ArrayUtility::isAssoc(["a","b"])
false
keepKeys
(array $array, array $keys, ArrayUtility::REMOVAL_ACTION_DELETE)
Same as CollectionUtility::keepKeys but operates on a basic array instead of a collection of arrays.
removeKeys
(array $array, array $keys, ArrayUtility::REMOVAL_ACTION_DELETE)
Same as CollectionUtility::removeKeys but operates on a basic array instead of a collection of arrays.
mapRecursive
(array $array, callable $callback, $map_arrays = false)
Like array walk recursive but doesn't mutate the array. Also, callback receives three arguments: $value, $key, $array
map
(array $array, callable $callback)
Like array_map but the callback receives three arguments: $value, $key, $array
first
(array $array)
Returns the first element from an array. More useful than reset() because it can handle the result of a function.
last
(array $array)
Returns the last element from an array. More useful than end() because it can handle the result of a function.
firstKey
(array $array)
Returns the key of the first element in an array.
lastKey
(array $array)
Returns the key of the last element in an array.
Install
Install UtilityBelt using Composer.
$ composer require rexlabs/utility-belt
Testing
UtilityBelt has a PHPUnit test suite. To run the tests, run the following command from the project folder.
$ composer test
Credits
License
The MIT License (MIT). Please see LICENSE for more information.