Skip to content

Latest commit

 

History

History
734 lines (556 loc) · 22.3 KB

README.md

File metadata and controls

734 lines (556 loc) · 22.3 KB
Raw

A wrapper class for PHP native arrays

Tests codecov Licence Badge Release Badge Tag Badge Issues Badge Code Size

A library that extends PHP's native string functionality

Compatibility and dependencies

This library is compatible with PHP version 7.2, 7.3, 7.4, 8.0, 8.1, 8.2 and 8.3.

This library has no dependencies.

Installation

Installation is simple using composer.

composer require kusabi/collections

Or simply add it to your composer.json file

{
    "require": {
        "kusabi/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 (7.2)

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 Kusabi\Collection\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 Kusabi\Collection\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 

// Getting the size of the collection
echo count($collection); // 5
echo $collection->count(); // 5

// Get the underlying array
$array = $collection->array();

A list of native methods integrated into this class

array_change_key_case Changes the case of all keys in an array

use Kusabi\Collection\Collection;

$collection = new Collection(["FirSt" => 1, "SecOnd" => 4]);

$collection->changeKeyCase(CASE_UPPER); // ["FIRST" => 1, "SECOND" => 4]
$collection->changeKeyCase(CASE_LOWER); // ["first" => 1, "second" => 4]

array_chunk Split an array into chunks

use Kusabi\Collection\Collection;

$collection = Collection::range(1, 100);
$chunks = $collection->chunk(10);

array_column Return the values from a single column in the input array

use Kusabi\Collection\Collection;

$collection = new Collection([
    'player_1' => [
        'name' => 'John',
        'hp' => 50,
        'exp' => 1000
    ],
    'player_2' => [
        'name' => 'Jane',
        'hp' => 70,
        'exp' => 1000
    ]
]);
$hps = $collection->column('hp'); // [50, 70]
$hps = $collection->column('hp', 'name'); // ['John' => 50, 'Jane' => 70]

array_combine Creates an array by using one array for keys and another for its values

use Kusabi\Collection\Collection;

$keys = new Collection(['a', 'b', 'c'])
$combinedWithArray = $keys->combine(['x', 'y', 'z']);
$combinedWithCollection = $keys->combine(new Collection(['x', 'y', 'z']));

array_count_values Counts all the values of an array

use Kusabi\Collection\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

use Kusabi\Collection\Collection;

$collection = new Collection([1, 2, 3, 4, 5, 6]);
$diff = $collection->diffAssoc([3, 4, 5]);
$diff = $collection->diffAssoc(new Collection([3, 4, 5]));

array_diff_key Computes the difference of arrays using keys for comparison

use Kusabi\Collection\Collection;

$collection = new Collection([1, 2, 3, 4, 5, 6]);
$diff = $collection->diffKeys([3, 4, 5]);
$diff = $collection->diffKeys(new Collection([3, 4, 5]));

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 Kusabi\Collection\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

use Kusabi\Collection\Collection;

$collection = Collection::fill(0, 10, 'a'); // ['a','a','a','a','a','a','a','a','a','a']

array_filter Filters elements of an array using a callback function

use Kusabi\Collection\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 Kusabi\Collection\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 Kusabi\Collection\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 Kusabi\Collection\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 Kusabi\Collection\Collection;

$collection = new Collection(['a' => 1, 'b' => 2, 'c' => 3]);
echo $collection->keys()->first(); // 'a'

array_key_last Gets the last key of an array

use Kusabi\Collection\Collection;

$collection = new Collection(['a' => 1, 'b' => 2, 'c' => 3]);
echo $collection->keys()->last(); // 'c'

array_keys Return all the keys or a subset of the keys of an array

use Kusabi\Collection\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 Kusabi\Collection\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

use Kusabi\Collection\Collection;

$a = new Collection([1, 2, 3]);
$b = $a->pad(10, 'a'); // [1, 2, 3, 'a', 'a', 'a', 'a', 'a', 'a', 'a']

array_pop Pop the element off the end of array

use Kusabi\Collection\Collection;

$collection = new Collection([1, 2, 3, 4]);
$popped = $collection->pop(); // [1, 2, 3]
echo $popped; // 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 Kusabi\Collection\Collection;

$collection = new Collection([1, 2, 3, 4]);
$collection->push(5, 6, 7, 8); // [1, 2, 3, 4, 5, 6, 7, 8]

array_rand Pick one or more random keys out of an array

// Add documentation

array_reduce Iteratively reduce the array to a single value using a callback function

use Kusabi\Collection\Collection;

$ten_factorial = Collection::range(1, 10)->reduce(function ($carry, $value) {
    return $carry * $value;
}, 1); // 3628800

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 Kusabi\Collection\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 Kusabi\Collection\Collection;

$collection = new Collection([1, 2, 3, 4]);
$shifted = $collection->shift(); // [2, 3, 4]
echo $shifted; // 1

array_slice Extract a slice of the array

use Kusabi\Collection\Collection;

Collection::range('a', 'j')->slice(2, 4); // ['c', 'd']

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 Kusabi\Collection\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

use Kusabi\Collection\Collection;

$collection = new Collection([1, 2, 3, 4]);
$collection->unshift(5, 6, 7, 8); // [5, 6, 7, 8, 1, 2, 3, 4]

array_values Return all the values of an array

use Kusabi\Collection\Collection;

$collection = new Collection(['a' => 1, 'b' => 2, 'c' => 3]);
$collection->values(5, 6, 7, 8); // [1, 2, 3]

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

array Create an array

arsort Sort an array in descending order and maintain index association

// Add documentation

asort Sort an array in ascending order and maintain index association

// Add documentation

compact Create array containing variables and their values

// Add documentation

count Counts all elements in an array or in a Countable object

use Kusabi\Collection\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

end Set the internal pointer of an array to its last element

// Add documentation

extract Import variables into the current symbol table from an array

use Kusabi\Collection\Collection;

$collection = new Collection(['a' => 1, 'b' => 2]);
extract($collection->array()); // No way to get the new variables into the caller scope. If we have collection->extract() then the variables will be created into the method scope

implode Join array elements with a string

use Kusabi\Collection\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

use Kusabi\Collection\Collection;

$collection = new Collection([4, 5, 6]);
$collection->contains(5);

key_exists Alias of array_key_exists

use Kusabi\Collection\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

key Fetch a key from an array

// Add documentation

krsort Sort an array by key in descending order

// Add documentation

ksort Sort an array by key in ascending order

// Add documentation

list Assign variables as if they were an array

// Add documentation

natcasesort Sort an array using a case insensitive "natural order" algorithm

// Add documentation

natsort Sort an array using a "natural order" algorithm

// Add documentation

next Advance the internal pointer of an array

// Add documentation

pos Alias of current

// Add documentation

prev Rewind the internal array pointer

// Add documentation

range Create an array containing a range of elements

use Kusabi\Collection\Collection;

$numbers = Collection::range(0, 100);
$even = Collection::range(0, 100, 2);
$alphabet = Collection::range('a', 'z');

reset Set the internal pointer of an array to its first element

// Add documentation

rsort Sort an array in descending order

// Add documentation

shuffle Shuffle an array

// Add documentation

sizeof Alias of count

use Kusabi\Collection\Collection;

$collection = new Collection([1, 2, 3]);

count($collection); // 3
$collection->count(); // 3

sort Sort an array in ascending order

// Add documentation

uasort Sort an array with a user-defined comparison function and maintain index association

// Add documentation

uksort Sort an array by keys using a user-defined comparison function

// Add documentation

usort Sort an array by values using a user-defined comparison function

// Add documentation