theodorejb/array-utils

Useful functions for working with arrays

v2.1.0 2023-09-13 23:36 UTC

Requires

• php: >=8.1

Requires (Dev)

• phpunit/phpunit: ^10.3
• psalm/plugin-phpunit: ^0.18.4
• vimeo/psalm: ^5.15

MIT

• Theodore Brown

README

ArrayUtils is a collection of useful PHP array functions.

Install via Composer

composer require theodorejb/array-utils

Methods

containsAll

Returns true if all the needles are in the haystack.

use theodorejb\ArrayUtils\ArrayUtils;

$haystack = [1, 2, 3, 5, 8, 13];
$needles = [2, 13, 5];
ArrayUtils::containsAll($needles, $haystack); // true
ArrayUtils::containsAll($haystack, $needles); // false

containsSame

Returns true if both arrays contain the same values (regardless of order).

use theodorejb\ArrayUtils\ArrayUtils;

$set1 = [1, 3, 5, 7];
$set2 = [3, 7, 5, 1];

ArrayUtils::containsSame($set1, $set2); // true

groupRows

Splits the iterable of arrays into groups when the value of one or more keys changes. The iterable must be sorted by the array keys used to group results.

use theodorejb\ArrayUtils\ArrayUtils;

$peoplePets = [
    ['lName' => 'Jordan', 'fName' => 'Jack', 'pet' => 'Scruffy'],
    ['lName' => 'Jordan', 'fName' => 'Jack', 'pet' => 'Spot'],
    ['lName' => 'Jordan', 'fName' => 'Jill', 'pet' => 'Paws'],
    ['lName' => 'Greene', 'fName' => 'Amy',  'pet' => 'Blackie'],
    ['lName' => 'Greene', 'fName' => 'Amy',  'pet' => 'Whiskers'],
    ['lName' => 'Greene', 'fName' => 'Amy',  'pet' => 'Paws'],
    ['lName' => 'Smith',  'fName' => 'Amy',  'pet' => 'Tiger'],
];

$grouped = [];

foreach (ArrayUtils::groupRows($peoplePets, 'fName') as $group) {
    $grouped[] = $group;
}

$expected = [
    [$peoplePets[0], $peoplePets[1]],
    [$peoplePets[2]],
    [$peoplePets[3], $peoplePets[4], $peoplePets[5], $peoplePets[6]],
];

var_dump($grouped === $expected); // bool(true)

////// Additional arguments can be passed to `groupRows` to group by more than one column:

$grouped = [];

foreach (ArrayUtils::groupRows($peoplePets, 'lName', 'fName') as $group) {
    $grouped[] = $group;
}

$expected = [
    [$peoplePets[0], $peoplePets[1]],
    [$peoplePets[2]],
    [$peoplePets[3], $peoplePets[4], $peoplePets[5]],
    [$peoplePets[6]],
];

var_dump($grouped === $expected); // bool(true)

requireStrKey

Returns the specified array key value if it is a string. Throws an exception otherwise.

use theodorejb\ArrayUtils\ArrayUtils;

$data = ['k' => 'val', 'i' => 1];
ArrayUtils::requireStrKey($data, 'k'); // val
ArrayUtils::requireStrKey($data, 'x'); // throws OutOfBoundsException
ArrayUtils::requireStrKey($data, 'i'); // throws UnexpectedValueException

getOptionalStrKey

Returns the specified array key value if it is a string, or null if the array key doesn't exist. Throws an exception if the key exists but the value is not a string.

use theodorejb\ArrayUtils\ArrayUtils;

$data = ['k' => 'val', 'i' => 1];
ArrayUtils::getOptionalStrKey($data, 'k'); // val
ArrayUtils::getOptionalStrKey($data, 'x'); // null
ArrayUtils::getOptionalStrKey($data, 'i'); // throws UnexpectedValueException

requireNumericKey

Returns the specified array key value as a float if it is an integer or float. Throws an exception otherwise.

use theodorejb\ArrayUtils\ArrayUtils;

$data = ['i' => 1, 'f' => 0.5, 'k' => 'val'];
ArrayUtils::requireNumericKey($data, 'i'); // 1.0
ArrayUtils::requireNumericKey($data, 'f'); // 0.5
ArrayUtils::requireNumericKey($data, 'x'); // throws OutOfBoundsException
ArrayUtils::requireNumericKey($data, 'k'); // throws UnexpectedValueException

getOptionalNumericKey

Returns the specified array key value as a float if it is an integer or float, or null if the array key doesn't exist. Throws an exception if the key exists but the value is not an integer or float.

use theodorejb\ArrayUtils\ArrayUtils;

$data = ['i' => 2, 'f' => 0.5, 'k' => 'val'];
ArrayUtils::getOptionalNumericKey($data, 'i'); // 2.0
ArrayUtils::getOptionalNumericKey($data, 'f'); // 0.5
ArrayUtils::getOptionalNumericKey($data, 'x'); // null
ArrayUtils::getOptionalNumericKey($data, 'k'); // throws UnexpectedValueException

requireIntKey

Returns the specified array key value if it is an integer. Throws an exception otherwise.

use theodorejb\ArrayUtils\ArrayUtils;

$data = ['k' => 'val', 'i' => 1];
ArrayUtils::requireIntKey($data, 'i'); // 1
ArrayUtils::requireIntKey($data, 'x'); // throws OutOfBoundsException
ArrayUtils::requireIntKey($data, 'k'); // throws UnexpectedValueException

getOptionalIntKey

Returns the specified array key value if it is an integer, or null if the array key doesn't exist. Throws an exception if the key exists but the value is not an integer.

use theodorejb\ArrayUtils\ArrayUtils;

$data = ['k' => 'val', 'i' => 2];
ArrayUtils::getOptionalIntKey($data, 'i'); // 2
ArrayUtils::getOptionalIntKey($data, 'x'); // null
ArrayUtils::getOptionalIntKey($data, 'k'); // throws UnexpectedValueException

requireBoolKey

Returns the specified array key value if it is a boolean. Throws an exception otherwise.

use theodorejb\ArrayUtils\ArrayUtils;

$data = ['k' => 'val', 'b' => true];
ArrayUtils::requireBoolKey($data, 'b'); // true
ArrayUtils::requireBoolKey($data, 'x'); // throws OutOfBoundsException
ArrayUtils::requireBoolKey($data, 'k'); // throws UnexpectedValueException

getOptionalBoolKey

Returns the specified array key value if it is a boolean, or null if the array key doesn't exist. Throws an exception if the key exists but the value is not a boolean.

use theodorejb\ArrayUtils\ArrayUtils;

$data = ['k' => 'val', 'b' => false];
ArrayUtils::getOptionalBoolKey($data, 'b'); // false
ArrayUtils::getOptionalBoolKey($data, 'x'); // null
ArrayUtils::getOptionalBoolKey($data, 'k'); // throws UnexpectedValueException

Author

Theodore Brown
https://theodorejb.me

License

MIT