Arr

Table of Contents

  1. Overview
  2. Basic Usage
  3. Methods
  4. Retrieving Data
  5. Iteration, Sorting, & Transformation
  6. Manipulation
  7. Comparison, Filtering, & Mapping
  8. Chunking and Collapsing
  9. Other Utilities


1. Overview Table of Contents

A collection of functions for manipulating arrays that are static and utility-based.

use Core\Lib\Utilities\Arr;


2. Basic Usage Table of Contents

$data = ['name' => 'John', 'age' => 30];

// Get a value using dot notation
echo Arr::get($data, 'name'); // John

// Sort values
$sorted = Arr::sort([5, 3, 8, 1]); 
print_r($sorted); // [1, 3, 5, 8]

// Filter
$filtered = Arr::filter([1, 2, 3, 4], fn($n) => $n > 2);
print_r($filtered); // [3, 4]

// Remove a key
$filtered = Arr::except(['name' => 'John', 'age' => 30], ['age']);
print_r($filtered); // ['name' => 'John']


3. Methods Table of Contents

A. add

add(array $array, string|int $key, mixed $value): array

Adds a value to an array if the key does not exist.

$array = ['name' => 'Alice'];
$array = Arr::add($array, 'age', 25);
print_r($array);
// ['name' => 'Alice', 'age' => 25]


B. arrayDivide

arrayDivide(array $array): array

Splits an array into two arrays: one with keys and one with values.

$array = ['name' => 'Alice', 'age' => 25];
list($keys, $values) = Arr::arrayDivide($array);
print_r($keys);
// ['name', 'age']
print_r($values);
// ['Alice', 25]


C. arrayPluckMulti

arrayPluckMulti(array $array, array|string $keys): array

Plucks nested values from an array.

$array = [
    ['name' => 'Alice', 'details' => ['age' => 25]],
    ['name' => 'Bob', 'details' => ['age' => 30]]
];
$result = Arr::arrayPluckMulti($array, 'details.age');
print_r($result);
// [25, 30]


D. arrayShuffleAssoc

arrayShuffleAssoc(array $array): array

Shuffles an associative array while preserving keys.

$array = ['a' => 1, 'b' => 2, 'c' => 3];
$shuffled = Arr::arrayShuffleAssoc($array);
print_r($shuffled);
// Example output: ['b' => 2, 'c' => 3, 'a' => 1]


E. chunk

chunk(array $array, int $size, bool $preserveKeys = false): array

Splits an array into chunks of a given size.

$array = [1, 2, 3, 4, 5];
$chunks = Arr::chunk($array, 2);
print_r($chunks);
// [[1, 2], [3, 4], [5]]


F. chunkBy

chunkBy(array $array, callable $callback): array

Chunks an array into groups based on a callback function.

$array = [1, 2, 2, 3, 3, 3, 4];
$chunks = Arr::chunkBy($array, fn($a, $b) => $a === $b);
print_r($chunks);
// [[1], [2, 2], [3, 3, 3], [4]]


G. collapse

collapse(array $array): array

Collapses a multi-dimensional array into a single-level array.

$array = [[1, 2], [3, 4], [5]];
$flattened = Arr::collapse($array);
print_r($flattened);
// [1, 2, 3, 4, 5]


H. contains

contains(array $array, mixed $value, bool $strict = false): bool

Determines if a given value exists in an array.

$array = [1, 2, 3, 'a' => 'apple'];
$result = Arr::contains($array, 'apple');
var_dump($result);
// true


I. crossJoin

crossJoin(array ...$arrays): array

Computes the Cartesian product of multiple arrays.

$array1 = [1, 2];
$array2 = ['a', 'b'];
$result = Arr::crossJoin($array1, $array2);
print_r($result);
// [[1, 'a'], [1, 'b'], [2, 'a'], [2, 'b']]


J. deepMerge

deepMerge(array ...$arrays): array

Recursively merges two or more arrays.

$array1 = ['name' => 'Alice', 'details' => ['age' => 25]];
$array2 = ['details' => ['city' => 'New York']];
$result = Arr::deepMerge($array1, $array2);
print_r($result);
// ['name' => 'Alice', 'details' => ['age' => 25, 'city' => 'New York']]


K. diffAssocRecursive

diffAssocRecursive(array $array1, array $array2): array

Recursively computes the difference between two arrays with keys.

$array1 = ['a' => 1, 'b' => ['x' => 10, 'y' => 20]];
$array2 = ['a' => 1, 'b' => ['x' => 10]];
$result = Arr::diffAssocRecursive($array1, $array2);
print_r($result);
// ['b' => ['y' => 20]]


L. dot

dot(array $array, string $prepend = ''): array

Converts a multi-dimensional array into dot notation keys.

$array = ['name' => 'Alice', 'details' => ['age' => 25, 'city' => 'New York']];
$result = Arr::dot($array);
print_r($result);
// ['name' => 'Alice', 'details.age' => 25, 'details.city' => 'New York']


4. Retrieving Data Table of Contents

A. except

except(array $array, array $keys): array

Gets all items except the specified keys.

$array = ['name' => 'Alice', 'age' => 25, 'city' => 'New York'];
$result = Arr::except($array, ['age']);
print_r($result);
// ['name' => 'Alice', 'city' => 'New York']


B. exists

exists(array $array, string|int $key): bool

Checks if a key exists in an array (non-dot notation).

$array = ['name' => 'Alice', 'age' => 25];
$result = Arr::exists($array, 'age');
var_dump($result);
// true


C. first

first(array $array, ?callable $callback = null, mixed $default = null): mixed

Gets the first element that passes a given test.

$array = [2, 4, 6, 8];
$result = Arr::first($array, fn($value) => $value > 4);
print_r($result);
// 6


D. get

get(array $array, string $key, mixed $default = null): mixed

Gets a value from an array using dot notation.

$array = ['name' => 'Alice', 'details' => ['age' => 25]];
$result = Arr::get($array, 'details.age');
print_r($result);
// 25


E. groupBy

groupBy(array $array, string $key): array

Groups an array by a given key.

$array = [
    ['id' => 1, 'category' => 'A'],
    ['id' => 2, 'category' => 'B'],
    ['id' => 3, 'category' => 'A']
];
$result = Arr::groupBy($array, 'category');
print_r($result);
// ['A' => [['id' => 1], ['id' => 3]], 'B' => [['id' => 2]]]


F. has

has(array $array, string $key): bool

Checks if an array has a given key using dot notation.

$array = ['name' => 'Alice', 'details' => ['age' => 25]];
$result = Arr::has($array, 'details.age');
var_dump($result);
// true


G. hasAllKeys

hasAllKeys(array $array, array $keys): bool

Checks if all given keys exist in the array.

$array = ['name' => 'Alice', 'age' => 25];
$result = Arr::hasAllKeys($array, ['name', 'age']);
var_dump($result);
// true


H. hasAnyKey

hasAnyKey(array $array, array $keys): bool

Checks if at least one key exists in the array.

$array = ['name' => 'Alice', 'age' => 25];
$result = Arr::hasAnyKey($array, ['age', 'gender']);
var_dump($result);
// true


I. keys

keys(array $array): array

Gets all the keys from an array.

$array = ['name' => 'Alice', 'age' => 25];
$result = Arr::keys($array);
print_r($result);
// ['name', 'age']


J. last

last(array $array, ?callable $callback = null, mixed $default = null): mixed

Gets the last element that passes a given test.

$array = [2, 4, 6, 8];
$result = Arr::last($array, fn($value) => $value < 7);
print_r($result);
// 6


K. only

only(array $array, array $keys): array

Gets only the specified keys from an array.

$array = ['name' => 'Alice', 'age' => 25, 'city' => 'New York'];
$result = Arr::only($array, ['name', 'city']);
print_r($result);
// ['name' => 'Alice', 'city' => 'New York']


L. pluck

pluck(array $array, string $value, ?string $key = null): array

Plucks a single key from an array.

$array = [
    ['id' => 1, 'name' => 'Alice'],
    ['id' => 2, 'name' => 'Bob']
];
$result = Arr::pluck($array, 'name');
print_r($result);
// ['Alice', 'Bob']


M. values

values(array $array): array

Gets all values from an array, resetting numeric keys.

$array = ['name' => 'Alice', 'age' => 25];
$result = Arr::values($array);
print_r($result);
// ['Alice', 25]


5. Iteration, Sorting, & Transformation Table of Contents

A. flatten

flatten(array $array, int $depth = INF): array

Flattens a multi-dimensional array into a single level.

$array = [[1, 2], [3, [4, 5]]];
$result = Arr::flatten($array);
print_r($result);
// [1, 2, 3, 4, 5]


B. flattenWithDepth

flattenWithDepth(array $array, int $depth = INF): array

Flattens an array up to a specified depth.

$array = [[1, 2], [3, [4, 5]]];
$result = Arr::flattenWithDepth($array, 1);
print_r($result);
// [1, 2, 3, [4, 5]]


C. flattenKeys

flattenKeys(array $array, string $prefix = ''): array

Converts a multi-dimensional array into dot notation keys.

$array = ['name' => 'Alice', 'details' => ['age' => 25, 'city' => 'New York']];
$result = Arr::flattenKeys($array);
print_r($result);
// ['name' => 'Alice', 'details.age' => 25, 'details.city' => 'New York']


D. map

map(array $array, callable $callback): array

Applies a callback to each item in an array.

$array = [1, 2, 3];
$result = Arr::map($array, fn($value) => $value * 2);
print_r($result);
// [2, 4, 6]


E. mapWithKeys

mapWithKeys(array $array, callable $callback): array

Maps an array while preserving keys.

$array = ['name' => 'Alice', 'age' => 25];
$result = Arr::mapWithKeys($array, fn($value, $key) => [$key => strtoupper($value)]);
print_r($result);
// ['name' => 'ALICE', 'age' => '25']


F. reverse

reverse(array $array, bool $preserveKeys = false): array

Reverses the order of elements in an array.

$array = [1, 2, 3, 4];
$result = Arr::reverse($array);
print_r($result);
// [4, 3, 2, 1]


G. shuffle

shuffle(array $array, ?int $seed = null): array

Shuffles the array.

$array = [1, 2, 3, 4, 5];
$result = Arr::shuffle($array);
print_r($result);
// Example output: [3, 1, 4, 5, 2]


H. sort

sort(array $array, ?callable $callback = null): array

Sorts an array using a callback function.

$array = [3, 1, 4, 1, 5, 9];
$result = Arr::sort($array);
print_r($result);
// [1, 1, 3, 4, 5, 9]


I. sortAssoc

sortAssoc(array $array, bool $descending = false): array

Sorts an associative array by its keys.

$array = ['b' => 2, 'a' => 1, 'c' => 3];
$result = Arr::sortAssoc($array);
print_r($result);
// ['a' => 1, 'b' => 2, 'c' => 3]


J. sortBy

sortBy(array $array, string $key, bool $descending = false): array

Sorts an array by a specific key.

$array = [
    ['name' => 'Alice', 'age' => 25],
    ['name' => 'Bob', 'age' => 20]
];
$result = Arr::sortBy($array, 'age');
print_r($result);
// [['name' => 'Bob', 'age' => 20], ['name' => 'Alice', 'age' => 25]]


K. sortByKeys

sortByKeys(array $array): array

Sorts an array by its keys.

$array = ['b' => 2, 'a' => 1, 'c' => 3];
$result = Arr::sortByKeys($array);
print_r($result);
// ['a' => 1, 'b' => 2, 'c' => 3]


L. sortByValues

sortByValues(array $array): array

Sorts an array by its values.

$array = ['b' => 3, 'a' => 1, 'c' => 2];
$result = Arr::sortByValues($array);
print_r($result);
// ['a' => 1, 'c' => 2, 'b' => 3]


6. Manipulation

A. fill

fill(int $startIndex, int $count, mixed $value): array

Fills an array with a specified value.

$result = Arr::fill(0, 3, 'a');
print_r($result);
// ['a', 'a', 'a']


B. forget

forget(array &$array, string|array $keys): void

Removes a value from an array using dot notation.

$array = ['name' => 'Alice', 'details' => ['age' => 25]];
Arr::forget($array, 'details.age');
print_r($array);
// ['name' => 'Alice', 'details' => []]


C. insertBefore

insertBefore(array $array, string|int $key, string|int $newKey, mixed $value): array

Inserts an element before a given key in an array.

$array = ['a' => 1, 'b' => 2];
$result = Arr::insertBefore($array, 'b', 'x', 99);
print_r($result);
// ['a' => 1, 'x' => 99, 'b' => 2]


D. insertAfter

insertAfter(array $array, string|int $key, string|int $newKey, mixed $value): array

Inserts an element after a given key in an array.

$array = ['a' => 1, 'b' => 2];
$result = Arr::insertAfter($array, 'a', 'x', 99);
print_r($result);
// ['a' => 1, 'x' => 99, 'b' => 2]


E. merge

merge(array ...$arrays): array

Merges one or more arrays together.

$array1 = ['name' => 'Alice'];
$array2 = ['age' => 25];
$result = Arr::merge($array1, $array2);
print_r($result);
// ['name' => 'Alice', 'age' => 25]


F. prepend

prepend(array $array, mixed $value, string|int|null $key = null): array

Prepends a value to an array.

$array = [2, 3, 4];
$result = Arr::prepend($array, 1);
print_r($result);
// [1, 2, 3, 4]


G. pull

pull(array &$array, string $key, mixed $default = null): mixed

Retrieves a value from the array and removes it.

$array = ['name' => 'Alice', 'age' => 25];
$age = Arr::pull($array, 'age');
print_r($age);
// 25
print_r($array);
// ['name' => 'Alice']


H. push

push(array &$array, mixed ...$values): array

Pushes one or more values onto the end of an array.

$array = [1, 2, 3];
Arr::push($array, 4, 5);
print_r($array);
// [1, 2, 3, 4, 5]


I. set

set(array &$array, string $key, mixed $value): void

Sets a value within an array using dot notation.

$array = ['name' => 'Alice'];
Arr::set($array, 'details.age', 25);
print_r($array);
// ['name' => 'Alice', 'details' => ['age' => 25]]


J. shift

shift(array &$array): mixed

Removes and returns the first element of an array.

$array = [1, 2, 3];
$first = Arr::shift($array);
print_r($first);
// 1
print_r($array);
// [2, 3]


K. swapKeys

swapKeys(array $array, string|int $key1, string|int $key2): array

Swaps two keys in an array.

$array = ['a' => 1, 'b' => 2];
$result = Arr::swapKeys($array, 'a', 'b');
print_r($result);
// ['a' => 2, 'b' => 1]


L. unsetKeys

unsetKeys(array $array, array $keys): array

Removes multiple keys from an array.

$array = ['name' => 'Alice', 'age' => 25, 'city' => 'New York'];
$result = Arr::unsetKeys($array, ['age', 'city']);
print_r($result);
// ['name' => 'Alice']


7. Comparison, Filtering, & Mapping Table of Contents

A. contains

contains(array $array, mixed $value, bool $strict = false): bool

Determines if a given value exists in an array.

$array = [1, 2, 3, 'a' => 'apple'];
$result = Arr::contains($array, 'apple');
var_dump($result);
// true


B. filter

filter(array $array, callable $callback): array

Filters an array using a callback function.

$array = [1, 2, 3, 4, 5];
$result = Arr::filter($array, fn($value) => $value > 2);
print_r($result);
// [3, 4, 5]


C. filterByKeys

filterByKeys(array $array, array $keys): array

Filters an array to include only the specified keys.

$array = ['name' => 'Alice', 'age' => 25, 'city' => 'New York'];
$result = Arr::filterByKeys($array, ['name', 'city']);
print_r($result);
// ['name' => 'Alice', 'city' => 'New York']


D. filterByValue

filterByValue(array $array, callable $callback): array

Filters an array by its values.

$array = ['a' => 1, 'b' => 2, 'c' => 3];
$result = Arr::filterByValue($array, fn($value) => $value > 1);
print_r($result);
// ['b' => 2, 'c' => 3]


E. partition

partition(array $array, callable $callback): array

Partitions an array into two groups: one where the callback returns true, the other where it returns false.

$array = [1, 2, 3, 4, 5];
list($even, $odd) = Arr::partition($array, fn($value) => $value % 2 === 0);
print_r($even);
// [2, 4]
print_r($odd);
// [1, 3, 5]


F. reject

reject(array $array, callable $callback): array

Rejects elements that match a given condition.

$array = [1, 2, 3, 4, 5];
$result = Arr::reject($array, fn($value) => $value > 3);
print_r($result);
// [1, 2, 3]


G. unique

unique(array $array): array

Removes duplicate values from an array.

$array = [1, 2, 2, 3, 3, 4];
$result = Arr::unique($array);
print_r($result);
// [1, 2, 3, 4]


H. uniqueBy

uniqueBy(array $array, string|callable $key): array

Removes duplicate items from an array based on a key or callback.

$array = [
    ['id' => 1, 'name' => 'Alice'],
    ['id' => 2, 'name' => 'Bob'],
    ['id' => 1, 'name' => 'Alice']
];
$result = Arr::uniqueBy($array, 'id');
print_r($result);
// [['id' => 1, 'name' => 'Alice'], ['id' => 2, 'name' => 'Bob']]


I. where

where(array $array, callable $callback): array

Filters an array using a callback function.

$array = [1, 2, 3, 4, 5];
$result = Arr::where($array, fn($value) => $value > 2);
print_r($result);
// [3, 4, 5]


8. Chunking & Collapsing Table of Contents

A. chunk

chunk(array $array, int $size, bool $preserveKeys = false): array

Splits an array into chunks of a given size.

$array = [1, 2, 3, 4, 5];
$result = Arr::chunk($array, 2);
print_r($result);
// [[1, 2], [3, 4], [5]]


B. chunkBy

chunkBy(array $array, callable $callback): array

Chunks an array into groups based on a callback function.

$array = [1, 2, 2, 3, 3, 3, 4];
$result = Arr::chunkBy($array, fn($a, $b) => $a === $b);
print_r($result);
// [[1], [2, 2], [3, 3, 3], [4]]


C. collapse

collapse(array $array): array

Collapses a multi-dimensional array into a single-level array.

$array = [[1, 2], [3, 4], [5]];
$result = Arr::collapse($array);
print_r($result);
// [1, 2, 3, 4, 5]


9. Other Utilities

A. isArray

isArray(mixed $value): bool

Determines if a given value is an array.

$result = Arr::isArray([1, 2, 3]);
var_dump($result);
// true


B. isAssoc

isAssoc(array $array): bool

Determines if an array is associative (i.e., contains at least one non-numeric key).

$array = ['a' => 1, 'b' => 2];
$result = Arr::isAssoc($array);
var_dump($result);
// true


C. isEmpty

isEmpty(?array $array): bool

Checks if the given array is empty.

$result = Arr::isEmpty([]);
var_dump($result);
// true


D. isNotEmpty

isNotEmpty(?array $array): bool

Checks if the given array is not empty.

$result = Arr::isNotEmpty([1, 2, 3]);
var_dump($result);
// true


E. random

random(array $array, ?int $number = null): mixed

Gets a random value or multiple values from an array.

$array = [1, 2, 3, 4, 5];
$result = Arr::random($array);
print_r($result);
// Example output: 3


F. toJson

toJson(array $array, int $options = 0): string

Converts an array to a JSON string.

$array = ['name' => 'Alice', 'age' => 25];
$result = Arr::toJson($array);
print_r($result);
// '{"name":"Alice","age":25}'


G. toObject

toObject(array $array): object

Converts an array to an object.

$array = ['name' => 'Alice', 'age' => 25];
$result = Arr::toObject($array);
print_r($result->name);
// Alice


H. unwrap

unwrap(array $array): mixed

Unwraps an array if it contains only one item.

$array = ['single'];
$result = Arr::unwrap($array);
print_r($result);
// 'single'


I. walkRecursive

walkRecursive(array $array, callable $callback): array

Recursively applies a callback function to each element in an array.

$array = [1, [2, 3], 4];
$result = Arr::walkRecursive($array, fn($value) => $value * 2);
print_r($result);
// [2, [4, 6], 8]


J. weightedRandom

weightedRandom(array $array, array $weights): mixed

Selects a random element based on weighted probabilities.

$items = ['apple', 'banana', 'cherry'];
$weights = [1, 2, 1];
$result = Arr::weightedRandom($items, $weights);
print_r($result);
// Example output: 'banana'


K. wrap

wrap(mixed $value): array

Wraps a value in an array.

$result = Arr::wrap('hello');
print_r($result);
// ['hello']


L. xorDiff

xorDiff(array $array1, array $array2): array

Computes the exclusive difference between two arrays.

$array1 = [1, 2, 3];
$array2 = [3, 4, 5];
$result = Arr::xorDiff($array1, $array2);
print_r($result);
// [1, 2, 4, 5]