barogue / collection
A class wrapper for PHP native arrays
Requires
- php: >=8.1
- barogue/arrays: ~1.0
Requires (Dev)
README
A class wrapper for PHP native arrays
Compatibility and dependencies
This library is compatible with PHP version 8.1
and 8.2
.
This library has no dependencies.
Installation
Installation is simple using composer.
composer require barogue/collections
Or simply add it to your composer.json
file
{ "require": { "barogue/collections": "^1.0" } }
Contributing
This library follows PSR-1 & PSR-2 standards.
Unit Tests
Before pushing any changes, please ensure the unit tests are all passing.
If possible, feel free to improve coverage in a separate commit.
vendor/bin/phpunit
Code sniffer
Before pushing, please ensure you have run the code sniffer. Only run it using the lowest support PHP version (8.1)
vendor/bin/php-cs-fixer fix
Static Analyses
Before pushing, please ensure you have run the static analyses tool.
vendor/bin/phan
Benchmarks
Before pushing, please ensure you have checked the benchmarks and ensured that your code has not introduced any slowdowns.
Feel free to speed up existing code, in a separate commit.
Feel free to add more benchmarks for greater coverage, in a separate commit.
vendor/bin/phpbench run --report=speed vendor/bin/phpbench run --report=speed --output=markdown vendor/bin/phpbench run --report=speed --filter=benchNetFromTax --iterations=50 --revs=50000 vendor/bin/phpbench xdebug:profile vendor/bin/phpbench xdebug:profile --gui
Documentation
This library adds a new class that can wrap around native arrays to mke interactions with them quicker and simpler.
Below you can find links to the documentation for the new features.
Creating an instance of the collection
use Barogue\Collections\Collection; // Using the constructor $collection = new Collection(); $collection = new Collection([1, 2, 3]); // Using the chainable constructor $collection = Collection::instance(); $collection = Collection::instance([1, 2, 3]); // Create using a range $celsius = Collection::range(0, 100); $alphabet = Collection::range('a', 'z'); $evens = Collection::range(0, 100, 2);
Getting data from a collection
use Barogue\Collections\Collection; // Collections can be used exactly like a normal array $collection = new Collection([1, 2, 3]); $collection[] = 4; $collection['test'] = 5; echo $collection[1]; // 2 // Get the original array $collection->getArray(); // Get an iterator $collection->getIterator(); // Getting the size of the collection echo count($collection); // 5 echo $collection->count(); // 5
A list of native methods integrated into this class
array_change_key_case Changes the case of all keys in an array
use Barogue\Collections\Collection; $collection = new Collection(["FirSt" => 1, "SecOnd" => 4]); $collection->changeKeyCase(CASE_UPPER); // ["FIRST" => 1, "SECOND" => 4] $collection->changeKeyCase(CASE_LOWER); // ["first" => 1, "second" => 4] $collection->changeKeyUpperCase(); // ["FIRST" => 1, "SECOND" => 4] $collection->changeKeyLowerCase(); // ["first" => 1, "second" => 4]
array_chunk Split an array into chunks
use Barogue\Collections\Collection; $collection = Collection::range(1, 100); $chunks = $collection->chunk(10);
array_column Return the values from a single column in the input array
use Barogue\Collections\Collection; $collection = new Collection([ 'player_1' => [ 'name' => 'John', 'stats' => [ 'hp' => 50, 'exp' => 1000 ] ], 'player_2' => [ 'name' => 'Jane', 'stats' => [ 'hp' => 70, 'exp' => 1000 ] ] ]); $hps = $collection->column('stats.hp'); // [50, 70] $hps = $collection->column('stats.hp', 'name'); // ['John' => 50, 'Jane' => 70]
array_combine Creates an array by using one array for keys and another for its values
use Barogue\Collections\Collection; $keys = new Collection(['a', 'b', 'c']); $combined = $keys->combine(1, 2, 3); // ['a' => 1, 'b' => 2, 'c' => 3] $combined = Collection::instance(['a', 'b', 'c'])->combine(1, 2, 3); // ['a' => 1, 'b' => 2, 'c' => 3]
array_count_values Counts all the values of an array
use Barogue\Collections\Collection; $collection = new Collection([1, 2, 3, 1, 2, 4, 'a', 'a', 1]); $appearances = $collection->countValues(); // [1 => 3, 2 => 2, 3 => 1, 4 => 1, 'a' => 2]
array_diff_assoc Computes the difference of arrays with additional index check
// Add documentation
array_diff_key Computes the difference of arrays using keys for comparison
// Add documentation
array_diff_uassoc Computes the difference of arrays with additional index check which is performed by a user supplied callback function
// Add documentation
array_diff_ukey Computes the difference of arrays using a callback function on the keys for comparison
// Add documentation
array_diff Computes the difference of arrays
use Barogue\Collections\Collection; $collection = new Collection([1, 2, 3, 4, 5, 6]); $diff = $collection->diff([3, 4, 5]); $diff = $collection->diff(new Collection([3, 4, 5]));
array_fill_keys Fill an array with values, specifying keys
// Add documentation
array_fill Fill an array with values
// Add documentation
array_filter Filters elements of an array using a callback function
use Barogue\Collections\Collection; $collection = new Collection([1, 2, 3, 4, 5, 6, null]); $collection->filter(); $collection->filter(function ($item) { return $item > 3; });
array_flip Exchanges all keys with their associated values in an array
use Barogue\Collections\Collection; $collection = new Collection(['a', 'b', 'c']); $flipped = $collection->flip(); // ['a' => 0, 'b' => 1, 'c' => 2] $collection = new Collection(['a', 'b', 'c', 'a']); $flipped = $collection->flip(); // ['a' => 0, 'b' => 1, 'c' => 2] $doubleFlipped = $collection->flip()->flip(); // ['a' => 0, 'b' => 1, 'c' => 2]
array_intersect_assoc Computes the intersection of arrays with additional index check
// Add documentation
array_intersect_key Computes the intersection of arrays using keys for comparison
// Add documentation
array_intersect_uassoc Computes the intersection of arrays with additional index check, compares indexes by a callback function
// Add documentation
array_intersect_ukey Computes the intersection of arrays using a callback function on the keys for comparison
// Add documentation
array_intersect Computes the intersection of arrays
// Add documentation
array_is_list Checks whether a given array is a list
use Barogue\Collections\Collection; Collection::instance(['a', 'b', 'c'])->isList(); // true Collection::instance(['a' => 1, 'b', 'c'])->isList(); // false
array_key_exists Checks if the given key or index exists in the array
use Barogue\Collections\Collection; $collection = new Collection([ 'a' => 1, 'b' => 2, 'c' => [ 'a' => 1, 'b' => null, 'c' => 3, ], ]); $collection->exists('a'); // true $collection->exists('z'); // false $collection->exists('c.a'); // true $collection->exists('c.b'); // true $collection->exists('c.z'); // false
array_key_first Gets the first key of an array
use Barogue\Collections\Collection; $collection = new Collection([ 'a' => 1, 'b' => 2, 'c' => 3, 'd' => 4, 'e' => 5, ]); $collection->firstKey(); // 'a' $collection->firstKey(fn($value, $key) => $value >= 3); // 'c' $collection->firstKey(fn($value, $key) => $key != 'a'); // 'b'
array_key_last Gets the last key of an array
use Barogue\Collections\Collection; $collection = new Collection([ 'a' => 1, 'b' => 2, 'c' => 3, 'd' => 4, 'e' => 5, ]); $collection->lastKey(); // 'e' $collection->lastKey(fn($value, $key) => $value >= 3); // 'e' $collection->lastKey(fn($value, $key) => $key != 'a'); // 'e'
array_keys Return all the keys or a subset of the keys of an array
use Barogue\Collections\Collection; $collection = new Collection([ 'a' => 1, 'b' => 2, 'c' => [ 'a' => 1, 'b' => null, 'c' => 3, ], ]); $collection->keys(); // ['a', 'b', 'c'] $collection->keys(true); // ['a', 'b', 'c.a', 'c.b', 'c.c']
array_map Applies the callback to the elements of the given arrays
use Barogue\Collections\Collection; $collection = new Collection([ 'a' => 1, 'b' => 2, 'c' => 3 ]); $increased = $collection->map(function ($value) { return $value * 2; }); // ['a' => 2, 'b' => 4, 'c' => 6] $concatenatedKeys = $collection->map(function ($value, $key) { return $key.'-'.$value; }); // ['a' => 'a-1', 'b' => 'b-2', 'c' => 'c-3']
array_merge_recursive Merge one or more arrays recursively
// Add documentation
array_merge Merge one or more arrays
// Add documentation
array_multisort Sort multiple or multi-dimensional arrays
// Add documentation
array_pad Pad array to the specified length with a value
// Add documentation
array_pop Pop the element off the end of array
use Barogue\Collections\Collection; $collection = new Collection([1, 2, 3, 4, 5, 6, 7, 8]); $single = $collection->pop(); // 8 $multiple = $collection->pop(4)->getArray(); // [7, 6, 5, 4]
array_product Calculate the product of values in an array
// Add documentation
array_push Push one or more elements onto the end of array
use Barogue\Collections\Collection; $collection = new Collection(); $collection->push('test'); // ['test'] $collection->push(1, 2, 3, 4, 5, 6); // ['test', 1, 2, 3, 4, 5]
array_rand Pick one or more random keys out of an array
use Barogue\Collections\Collection; $collection = new Collection([ 'a' => 1, 'b' => 2, 'c' => 3 ]); $collection->randomKey(); // 'b' $collection->randomKeys(2)->getArray(); // ['c', 'a']
array_reduce Iteratively reduce the array to a single value using a callback function
use Barogue\Collections\Collection; $factorial = Collection::range(10, 1)->reduce(fn($carry, $value) => $carry * $value, 1) $factorial = Collection::factorial(10)
array_replace_recursive Replaces elements from passed arrays into the first array recursively
// Add documentation
array_replace Replaces elements from passed arrays into the first array
// Add documentation
array_reverse Return an array with elements in reverse order
use Barogue\Collections\Collection; $collection = new Collection([ 'a' => 1, 'b' => 2, 'c' => 3 ]); $reversedCopy = $collection->reverse(); // ['c' => 3, 'b' => 2, 'a' => 1]
array_search Searches the array for a given value and returns the first corresponding key if successful
// Add documentation
array_shift Shift an element off the beginning of array
use Barogue\Collections\Collection; $collection = new Collection([1, 2, 3, 4, 5, 6, 7, 8]); $single = $collection->shift(); // 1 $multiple = $collection->shift(4)->getArray(); // [2, 3, 4, 5]
array_slice Extract a slice of the array
// Add documentation
array_splice Remove a portion of the array and replace it with something else
// Add documentation
array_sum Calculate the sum of values in an array
use Barogue\Collections\Collection; $sum = Collection::instance([1, 2, 3])->sum(); // 6 $sum = Collection::range(1, 100)->sum(); // 5050
array_udiff_assoc Computes the difference of arrays with additional index check, compares data by a callback function
// Add documentation
array_udiff_uassoc Computes the difference of arrays with additional index check, compares data and indexes by a callback function
// Add documentation
array_udiff Computes the difference of arrays by using a callback function for data comparison
// Add documentation
array_uintersect_assoc Computes the intersection of arrays with additional index check, compares data by a callback function
// Add documentation
array_uintersect_uassoc Computes the intersection of arrays with additional index check, compares data and indexes by separate callback functions
// Add documentation
array_uintersect Computes the intersection of arrays, compares data by a callback function
// Add documentation
array_unique Removes duplicate values from an array
// Add documentation
array_unshift Prepend one or more elements to the beginning of an array
// Add documentation
array_values Return all the values of an array
use Barogue\Collections\Collection; $values = Collection::instance(['a' => 1, 'b' => 2])->values()->getArray(); // [1, 2]
array_walk_recursive Apply a user function recursively to every member of an array
// Add documentation
array_walk Apply a user supplied function to every member of an array
// Add documentation
arsort Sort an array in descending order and maintain index association
use Barogue\Collections\Collection; $collection = new Collection(['a' => 9, 'b' => 1, 'c' => 5]); $collection->reverseSort(); // ['a' => 9, 'c' => 5, 'b' => 1]
asort Sort an array in ascending order and maintain index association
use Barogue\Collections\Collection; $collection = new Collection(['a' => 9, 'b' => 5, 'c' => 1]); $collection->sort(); // ['c' => 1, 'b' => 5, 'a' => 9]
compact Create array containing variables and their values
// Add documentation
count Counts all elements in an array or in a Countable object
use Barogue\Collections\Collection; $collection = new Collection([1, 2, 3]); count($collection); // 3 $collection->count(); // 3
current Return the current element in an array
// Add documentation
each Return the current key and value pair from an array and advance the array cursor
// Add documentation
extract Import variables into the current symbol table from an array
// Add documentation
implode Join array elements with a string
use Barogue\Collections\Collection; echo Collection::instance('a', 'b', 'c')->implode(', '); // "a, b, c" echo Collection::instance('a', 'b', 'c')->implode(', ', ' and '); // "a, b and c"
in_array Checks if a value exists in an array
// Add documentation
krsort Sort an array by key in descending order
use Barogue\Collections\Collection; $collection = new Collection(['a' => 5, 'c' => 4, 'z' => 3, 'b' => 2, 'e' => 1]); $sorted = $collection->sortKeys()->reverse(); // ['z' => 3, 'e' => 1, 'c' => 4, 'b' => 2, 'a' => 5]
ksort Sort an array by key in ascending order
use Barogue\Collections\Collection; $collection = new Collection(['a' => 5, 'c' => 4, 'z' => 3, 'b' => 2, 'e' => 1]); $sorted = $collection->sortKeys(); // ['a' => 5, 'b' => 2, 'c' => 4, 'e' => 1, 'z' => 3]
list Assign variables as if they were an array
use Barogue\Collections\Collection; $collection = new Collection(['coffee', 'brown', 'caffeine']); list($drink, $color, $power) = $collection; echo $drink; // coffee echo $color; // brown echo $power; // caffeine
natcasesort Sort an array using a case insensitive "natural order" algorithm
// Add documentation
natsort Sort an array using a "natural order" algorithm
// Add documentation
range Create an array containing a range of elements
use Barogue\Collections\Collection; $numbers = Collection::range(0, 100); $even = Collection::range(0, 100, 2); $alphabet = Collection::range('a', 'z');
rsort Sort an array in descending order
use Barogue\Collections\Collection; $collection = new Collection(['a' => 9, 'b' => 1, 'c' => 5]); $collection->reverseSort()->values(); // [9, 5, 1]
shuffle Shuffle an array
use Barogue\Collections\Collection; $collection = new Collection(['a' => 1, 'b' => 2, 'c' => 3]); $collection->shuffle(); // ['b' => 2, 'c' => 3, 'a' => 1] $collection->shuffle(false); // [3, 1, 2]
sizeof Alias of count
use Barogue\Collections\Collection; $collection = new Collection([1, 2, 3]); count($collection); // 3 $collection->count(); // 3
sort Sort an array in ascending order
use Barogue\Collections\Collection; $collection = new Collection(['a' => 9, 'b' => 5, 'c' => 1]); $collection->sort()->values(); // [1, 5, 9]
uasort Sort an array with a user-defined comparison function and maintain index association
use Barogue\Collections\Collection; $collection = new Collection([5, 4, 3, 2, 1]); $collection->sortCallback(function($a, $b) { $aEven = $a % 2 == 0 ? 1 : 0; $bEven = $b % 2 == 0 ? 1 : 0; return $aEven === $bEven ? $a <=> $b : $aEven <=> $bEven; }); // [4 => 1, 2 => 3, 0 => 5, 3 => 2, 1 => 4]
uksort Sort an array by keys using a user-defined comparison function
use Barogue\Collections\Collection; $collection = new Collection([5, 4, 3, 2, 1]); $collection->sortCallback(function($a, $b) { $aEven = $a % 2 == 0 ? 1 : 0; $bEven = $b % 2 == 0 ? 1 : 0; return $aEven === $bEven ? $a <=> $b : $aEven <=> $bEven; }); // [1 => 4, 3 => 2, 0 => 5, 2 => 3, 4 => 1]
usort Sort an array by values using a user-defined comparison function
use Barogue\Collections\Collection; $collection = new Collection([5, 4, 3, 2, 1]); $collection->sortCallback(function($a, $b) { $aEven = $a % 2 == 0 ? 1 : 0; $bEven = $b % 2 == 0 ? 1 : 0; return $aEven === $bEven ? $a <=> $b : $aEven <=> $bEven; })->values(); // [1, 3, 5, 2, 4]