Arr.php
TLDR
This file, Arr.php, is a part of the Illuminate\Support namespace in the Demo Projects project. It contains a class named Arr that provides various utility methods for working with arrays.
Methods
accessible($value)
This method determines whether the given value is array accessible. It checks if the value is an array or an instance of ArrayAccess.
add($array, $key, $value)
This method adds an element to an array using "dot" notation if it doesn't already exist. It takes an array, a key, and a value as arguments and returns the updated array.
collapse($array)
This method collapses an array of arrays into a single array. It iterates through the array and adds each element to the resulting array. If an element is an instance of Collection, it converts it to an array before adding it.
crossJoin(...$arrays)
This method performs a cross join on the given arrays, returning all possible permutations. It uses nested loops to combine each element from each array with each element from other arrays.
divide($array)
This method divides an array into two arrays. One array contains the keys and the other array contains the values.
dot($array, $prepend = '')
This method flattens a multi-dimensional associative array with dots. It iterates through the array and converts each key-value pair into a dot notation format. If the value is an array, it recursively calls itself to flatten the nested arrays.
undot($array)
This method converts a flatten "dot" notation array into an expanded array. It iterates through the array and sets each key-value pair in the resulting array.
except($array, $keys)
This method returns all elements from the given array except for the specified keys. It calls the forget method to remove the specified keys from the array.
exists($array, $key)
This method determines if the given key exists in the provided array. It checks if the array is an instance of ArrayAccess or if the key exists in the array using array_key_exists.
first($array, $callback = null, $default = null)
This method returns the first element in an array that passes a given truth test. If no callback is provided, it returns the first element of the array. If the array is empty, it returns the default value.
last($array, $callback = null, $default = null)
This method returns the last element in an array that passes a given truth test. If no callback is provided, it returns the last element of the array. If the array is empty, it returns the default value.
flatten($array, $depth = INF)
This method flattens a multi-dimensional array into a single level array. It recursively iterates through the array and adds each element to the resulting array. The depth parameter determines the depth until which the flattening should be performed.
forget(&$array, $keys)
This method removes one or many array items from a given array using "dot" notation. It checks if the exact key exists in the top-level and removes it. If the key contains dots, it traverses the nested arrays and removes the corresponding key.
get($array, $key, $default = null)
This method gets an item from an array using "dot" notation. It checks if the array is array accessible, if the key exists in the array, and if the key contains dots to handle nested arrays.
has($array, $keys)
This method checks if an item or items exist in an array using "dot" notation. It checks if the array is empty or if the keys exist in the array or its nested arrays.
hasAny($array, $keys)
This method determines if any of the keys exist in an array using "dot" notation. It checks if the keys exist in the array or its nested arrays and returns true if at least one key is found.
isAssoc($array)
This method determines if an array is associative. An array is "associative" if it doesn't have sequential numerical keys beginning with zero.
isList($array)
This method determines if an array is a list. An array is a "list" if all array keys are sequential integers starting from 0 with no gaps in between.
join($array, $glue, $finalGlue = '')
This method joins all items in the array using a glue string. The final items can use a separate glue string. It checks the number of items in the array and returns the desired output accordingly.
keyBy($array, $keyBy)
This method keys an associative array by a field or using a callback. It uses the keyBy method from the Collection class to perform the keying.
prependKeysWith($array, $prependWith)
This method prepends the key names of an associative array with a specified string. It uses the mapWithKeys method from the Collection class to perform the key modification.
only($array, $keys)
This method gets a subset of the items from the given array. It uses the array_intersect_key function to filter the array with the specified keys.
pluck($array, $value, $key = null)
This method plucks an array of values from an array. It retrieves the specified value from each item in the array using "dot" notation. If a key is provided, it also retrieves the corresponding key. The resulting array is returned.
map($array, $callback)
This method runs a map over each of the items in the array using the provided callback. It applies the callback function to each item in the array and returns an array with the results.
mapWithKeys($array, $callback)
This method runs an associative map over each of the items in the array using the provided callback. The callback should return an associative array with a single key/value pair. It returns an array with the results.
prepend($array, $value, $key = null)
This method pushes an item onto the beginning of an array. It can either push the item directly or prepend it with a specified key.
pull(&$array, $key, $default = null)
This method gets a value from the array and removes it from the array. It uses the get method to retrieve the value and the forget method to remove the key-value pair from the array.
query($array)
This method converts the array into a query string. It uses the http_build_query function to build the query string.
random($array, $number = null, $preserveKeys = false)
This method gets one or a specified number of random values from an array. It uses the array_rand function to generate random keys and retrieves the corresponding values from the array.
set(&$array, $key, $value)
This method sets an array item to a given value using "dot" notation. If no key is given, it replaces the entire array. It modifies the original array by reference and returns it.
shuffle($array, $seed = null)
This method shuffles the given array and returns the result. It uses the shuffle function with a random seed if provided.
sort($array, $callback = null)
This method sorts the array using the given callback or "dot" notation. It uses the sortBy method from the Collection class to perform the sorting.
sortDesc($array, $callback = null)
This method sorts the array in descending order using the given callback or "dot" notation. It uses the sortByDesc method from the Collection class to perform the sorting.
sortRecursive($array, $options = SORT_REGULAR, $descending = false)
This method recursively sorts an array by keys and values. It uses the array_krsort and array_rsort functions for associative and list arrays, respectively.
sortRecursiveDesc($array, $options = SORT_REGULAR)
This method recursively sorts an array by keys and values in descending order. It calls the sortRecursive method with the descending flag set to true.
toCssClasses($array)
This method conditionally compiles classes from an array into a CSS class list. It wraps each array item in a key-value pair and checks if the value is truthy to include the key (class) in the resulting string.
toCssStyles($array)
This method conditionally compiles styles from an array into a style list. It wraps each array item in a key-value pair and checks if the value is truthy to include the key (style) in the resulting string.
where($array, $callback)
This method filters the array using the given callback. It applies the callback function to each item in the array and returns a new array with the items that pass the callback test.
whereNotNull($array)
This method filters items in the array where the value is not null. It uses the where method with a callback that checks if the value is not null.
wrap($value)
This method wraps the given value in an array if it is not already an array or null. If the value is null, an empty array is returned. Otherwise, the value is wrapped in an array.
<?php
namespace Illuminate\Support;
use ArgumentCountError;
use ArrayAccess;
use Illuminate\Support\Traits\Macroable;
use InvalidArgumentException;
class Arr
{
use Macroable;
/**
* Determine whether the given value is array accessible.
*
* @param mixed $value
* @return bool
*/
public static function accessible($value)
{
return is_array($value) || $value instanceof ArrayAccess;
}
/**
* Add an element to an array using "dot" notation if it doesn't exist.
*
* @param array $array
* @param string|int|float $key
* @param mixed $value
* @return array
*/
public static function add($array, $key, $value)
{
if (is_null(static::get($array, $key))) {
static::set($array, $key, $value);
}
return $array;
}
/**
* Collapse an array of arrays into a single array.
*
* @param iterable $array
* @return array
*/
public static function collapse($array)
{
$results = [];
foreach ($array as $values) {
if ($values instanceof Collection) {
$values = $values->all();
} elseif (! is_array($values)) {
continue;
}
$results[] = $values;
}
return array_merge([], ...$results);
}
/**
* Cross join the given arrays, returning all possible permutations.
*
* @param iterable ...$arrays
* @return array
*/
public static function crossJoin(...$arrays)
{
$results = [[]];
foreach ($arrays as $index => $array) {
$append = [];
foreach ($results as $product) {
foreach ($array as $item) {
$product[$index] = $item;
$append[] = $product;
}
}
$results = $append;
}
return $results;
}
/**
* Divide an array into two arrays. One with keys and the other with values.
*
* @param array $array
* @return array
*/
public static function divide($array)
{
return [array_keys($array), array_values($array)];
}
/**
* Flatten a multi-dimensional associative array with dots.
*
* @param iterable $array
* @param string $prepend
* @return array
*/
public static function dot($array, $prepend = '')
{
$results = [];
foreach ($array as $key => $value) {
if (is_array($value) && ! empty($value)) {
$results[] = static::dot($value, $prepend.$key.'.');
} else {
$results[] = [$prepend.$key => $value];
}
}
return array_merge(...$results);
}
/**
* Convert a flatten "dot" notation array into an expanded array.
*
* @param iterable $array
* @return array
*/
public static function undot($array)
{
$results = [];
foreach ($array as $key => $value) {
static::set($results, $key, $value);
}
return $results;
}
/**
* Get all of the given array except for a specified array of keys.
*
* @param array $array
* @param array|string|int|float $keys
* @return array
*/
public static function except($array, $keys)
{
static::forget($array, $keys);
return $array;
}
/**
* Determine if the given key exists in the provided array.
*
* @param \ArrayAccess|array $array
* @param string|int $key
* @return bool
*/
public static function exists($array, $key)
{
if ($array instanceof Enumerable) {
return $array->has($key);
}
if ($array instanceof ArrayAccess) {
return $array->offsetExists($key);
}
if (is_float($key)) {
$key = (string) $key;
}
return array_key_exists($key, $array);
}
/**
* Return the first element in an array passing a given truth test.
*
* @param iterable $array
* @param callable|null $callback
* @param mixed $default
* @return mixed
*/
public static function first($array, callable $callback = null, $default = null)
{
if (is_null($callback)) {
if (empty($array)) {
return value($default);
}
foreach ($array as $item) {
return $item;
}
return value($default);
}
foreach ($array as $key => $value) {
if ($callback($value, $key)) {
return $value;
}
}
return value($default);
}
/**
* Return the last element in an array passing a given truth test.
*
* @param array $array
* @param callable|null $callback
* @param mixed $default
* @return mixed
*/
public static function last($array, callable $callback = null, $default = null)
{
if (is_null($callback)) {
return empty($array) ? value($default) : end($array);
}
return static::first(array_reverse($array, true), $callback, $default);
}
/**
* Flatten a multi-dimensional array into a single level.
*
* @param iterable $array
* @param int $depth
* @return array
*/
public static function flatten($array, $depth = INF)
{
$result = [];
foreach ($array as $item) {
$item = $item instanceof Collection ? $item->all() : $item;
if (! is_array($item)) {
$result[] = $item;
} else {
$values = $depth === 1
? array_values($item)
: static::flatten($item, $depth - 1);
foreach ($values as $value) {
$result[] = $value;
}
}
}
return $result;
}
/**
* Remove one or many array items from a given array using "dot" notation.
*
* @param array $array
* @param array|string|int|float $keys
* @return void
*/
public static function forget(&$array, $keys)
{
$original = &$array;
$keys = (array) $keys;
if (count($keys) === 0) {
return;
}
foreach ($keys as $key) {
// if the exact key exists in the top-level, remove it
if (static::exists($array, $key)) {
unset($array[$key]);
continue;
}
$parts = explode('.', $key);
// clean up before each pass
$array = &$original;
while (count($parts) > 1) {
$part = array_shift($parts);
if (isset($array[$part]) && static::accessible($array[$part])) {
$array = &$array[$part];
} else {
continue 2;
}
}
unset($array[array_shift($parts)]);
}
}
/**
* Get an item from an array using "dot" notation.
*
* @param \ArrayAccess|array $array
* @param string|int|null $key
* @param mixed $default
* @return mixed
*/
public static function get($array, $key, $default = null)
{
if (! static::accessible($array)) {
return value($default);
}
if (is_null($key)) {
return $array;
}
if (static::exists($array, $key)) {
return $array[$key];
}
if (! str_contains($key, '.')) {
return $array[$key] ?? value($default);
}
foreach (explode('.', $key) as $segment) {
if (static::accessible($array) && static::exists($array, $segment)) {
$array = $array[$segment];
} else {
return value($default);
}
}
return $array;
}
/**
* Check if an item or items exist in an array using "dot" notation.
*
* @param \ArrayAccess|array $array
* @param string|array $keys
* @return bool
*/
public static function has($array, $keys)
{
$keys = (array) $keys;
if (! $array || $keys === []) {
return false;
}
foreach ($keys as $key) {
$subKeyArray = $array;
if (static::exists($array, $key)) {
continue;
}
foreach (explode('.', $key) as $segment) {
if (static::accessible($subKeyArray) && static::exists($subKeyArray, $segment)) {
$subKeyArray = $subKeyArray[$segment];
} else {
return false;
}
}
}
return true;
}
/**
* Determine if any of the keys exist in an array using "dot" notation.
*
* @param \ArrayAccess|array $array
* @param string|array $keys
* @return bool
*/
public static function hasAny($array, $keys)
{
if (is_null($keys)) {
return false;
}
$keys = (array) $keys;
if (! $array) {
return false;
}
if ($keys === []) {
return false;
}
foreach ($keys as $key) {
if (static::has($array, $key)) {
return true;
}
}
return false;
}
/**
* Determines if an array is associative.
*
* An array is "associative" if it doesn't have sequential numerical keys beginning with zero.
*
* @param array $array
* @return bool
*/
public static function isAssoc(array $array)
{
return ! array_is_list($array);
}
/**
* Determines if an array is a list.
*
* An array is a "list" if all array keys are sequential integers starting from 0 with no gaps in between.
*
* @param array $array
* @return bool
*/
public static function isList($array)
{
return array_is_list($array);
}
/**
* Join all items using a string. The final items can use a separate glue string.
*
* @param array $array
* @param string $glue
* @param string $finalGlue
* @return string
*/
public static function join($array, $glue, $finalGlue = '')
{
if ($finalGlue === '') {
return implode($glue, $array);
}
if (count($array) === 0) {
return '';
}
if (count($array) === 1) {
return end($array);
}
$finalItem = array_pop($array);
return implode($glue, $array).$finalGlue.$finalItem;
}
/**
* Key an associative array by a field or using a callback.
*
* @param array $array
* @param callable|array|string $keyBy
* @return array
*/
public static function keyBy($array, $keyBy)
{
return Collection::make($array)->keyBy($keyBy)->all();
}
/**
* Prepend the key names of an associative array.
*
* @param array $array
* @param string $prependWith
* @return array
*/
public static function prependKeysWith($array, $prependWith)
{
return Collection::make($array)->mapWithKeys(function ($item, $key) use ($prependWith) {
return [$prependWith.$key => $item];
})->all();
}
/**
* Get a subset of the items from the given array.
*
* @param array $array
* @param array|string $keys
* @return array
*/
public static function only($array, $keys)
{
return array_intersect_key($array, array_flip((array) $keys));
}
/**
* Pluck an array of values from an array.
*
* @param iterable $array
* @param string|array|int|null $value
* @param string|array|null $key
* @return array
*/
public static function pluck($array, $value, $key = null)
{
$results = [];
[$value, $key] = static::explodePluckParameters($value, $key);
foreach ($array as $item) {
$itemValue = data_get($item, $value);
// If the key is "null", we will just append the value to the array and keep
// looping. Otherwise we will key the array using the value of the key we
// received from the developer. Then we'll return the final array form.
if (is_null($key)) {
$results[] = $itemValue;
} else {
$itemKey = data_get($item, $key);
if (is_object($itemKey) && method_exists($itemKey, '__toString')) {
$itemKey = (string) $itemKey;
}
$results[$itemKey] = $itemValue;
}
}
return $results;
}
/**
* Explode the "value" and "key" arguments passed to "pluck".
*
* @param string|array $value
* @param string|array|null $key
* @return array
*/
protected static function explodePluckParameters($value, $key)
{
$value = is_string($value) ? explode('.', $value) : $value;
$key = is_null($key) || is_array($key) ? $key : explode('.', $key);
return [$value, $key];
}
/**
* Run a map over each of the items in the array.
*
* @param array $array
* @param callable $callback
* @return array
*/
public static function map(array $array, callable $callback)
{
$keys = array_keys($array);
try {
$items = array_map($callback, $array, $keys);
} catch (ArgumentCountError) {
$items = array_map($callback, $array);
}
return array_combine($keys, $items);
}
/**
* Run an associative map over each of the items.
*
* The callback should return an associative array with a single key/value pair.
*
* @template TKey
* @template TValue
* @template TMapWithKeysKey of array-key
* @template TMapWithKeysValue
*
* @param array<TKey, TValue> $array
* @param callable(TValue, TKey): array<TMapWithKeysKey, TMapWithKeysValue> $callback
* @return array
*/
public static function mapWithKeys(array $array, callable $callback)
{
$result = [];
foreach ($array as $key => $value) {
$assoc = $callback($value, $key);
foreach ($assoc as $mapKey => $mapValue) {
$result[$mapKey] = $mapValue;
}
}
return $result;
}
/**
* Push an item onto the beginning of an array.
*
* @param array $array
* @param mixed $value
* @param mixed $key
* @return array
*/
public static function prepend($array, $value, $key = null)
{
if (func_num_args() == 2) {
array_unshift($array, $value);
} else {
$array = [$key => $value] + $array;
}
return $array;
}
/**
* Get a value from the array, and remove it.
*
* @param array $array
* @param string|int $key
* @param mixed $default
* @return mixed
*/
public static function pull(&$array, $key, $default = null)
{
$value = static::get($array, $key, $default);
static::forget($array, $key);
return $value;
}
/**
* Convert the array into a query string.
*
* @param array $array
* @return string
*/
public static function query($array)
{
return http_build_query($array, '', '&', PHP_QUERY_RFC3986);
}
/**
* Get one or a specified number of random values from an array.
*
* @param array $array
* @param int|null $number
* @param bool $preserveKeys
* @return mixed
*
* @throws \InvalidArgumentException
*/
public static function random($array, $number = null, $preserveKeys = false)
{
$requested = is_null($number) ? 1 : $number;
$count = count($array);
if ($requested > $count) {
throw new InvalidArgumentException(
"You requested {$requested} items, but there are only {$count} items available."
);
}
if (is_null($number)) {
return $array[array_rand($array)];
}
if ((int) $number === 0) {
return [];
}
$keys = array_rand($array, $number);
$results = [];
if ($preserveKeys) {
foreach ((array) $keys as $key) {
$results[$key] = $array[$key];
}
} else {
foreach ((array) $keys as $key) {
$results[] = $array[$key];
}
}
return $results;
}
/**
* Set an array item to a given value using "dot" notation.
*
* If no key is given to the method, the entire array will be replaced.
*
* @param array $array
* @param string|int|null $key
* @param mixed $value
* @return array
*/
public static function set(&$array, $key, $value)
{
if (is_null($key)) {
return $array = $value;
}
$keys = explode('.', $key);
foreach ($keys as $i => $key) {
if (count($keys) === 1) {
break;
}
unset($keys[$i]);
// If the key doesn't exist at this depth, we will just create an empty array
// to hold the next value, allowing us to create the arrays to hold final
// values at the correct depth. Then we'll keep digging into the array.
if (! isset($array[$key]) || ! is_array($array[$key])) {
$array[$key] = [];
}
$array = &$array[$key];
}
$array[array_shift($keys)] = $value;
return $array;
}
/**
* Shuffle the given array and return the result.
*
* @param array $array
* @param int|null $seed
* @return array
*/
public static function shuffle($array, $seed = null)
{
if (is_null($seed)) {
shuffle($array);
} else {
mt_srand($seed);
shuffle($array);
mt_srand();
}
return $array;
}
/**
* Sort the array using the given callback or "dot" notation.
*
* @param array $array
* @param callable|array|string|null $callback
* @return array
*/
public static function sort($array, $callback = null)
{
return Collection::make($array)->sortBy($callback)->all();
}
/**
* Sort the array in descending order using the given callback or "dot" notation.
*
* @param array $array
* @param callable|array|string|null $callback
* @return array
*/
public static function sortDesc($array, $callback = null)
{
return Collection::make($array)->sortByDesc($callback)->all();
}
/**
* Recursively sort an array by keys and values.
*
* @param array $array
* @param int $options
* @param bool $descending
* @return array
*/
public static function sortRecursive($array, $options = SORT_REGULAR, $descending = false)
{
foreach ($array as &$value) {
if (is_array($value)) {
$value = static::sortRecursive($value, $options, $descending);
}
}
if (! array_is_list($array)) {
$descending
? krsort($array, $options)
: ksort($array, $options);
} else {
$descending
? rsort($array, $options)
: sort($array, $options);
}
return $array;
}
/**
* Recursively sort an array by keys and values in descending order.
*
* @param array $array
* @param int $options
* @return array
*/
public static function sortRecursiveDesc($array, $options = SORT_REGULAR)
{
return static::sortRecursive($array, $options, true);
}
/**
* Conditionally compile classes from an array into a CSS class list.
*
* @param array $array
* @return string
*/
public static function toCssClasses($array)
{
$classList = static::wrap($array);
$classes = [];
foreach ($classList as $class => $constraint) {
if (is_numeric($class)) {
$classes[] = $constraint;
} elseif ($constraint) {
$classes[] = $class;
}
}
return implode(' ', $classes);
}
/**
* Conditionally compile styles from an array into a style list.
*
* @param array $array
* @return string
*/
public static function toCssStyles($array)
{
$styleList = static::wrap($array);
$styles = [];
foreach ($styleList as $class => $constraint) {
if (is_numeric($class)) {
$styles[] = Str::finish($constraint, ';');
} elseif ($constraint) {
$styles[] = Str::finish($class, ';');
}
}
return implode(' ', $styles);
}
/**
* Filter the array using the given callback.
*
* @param array $array
* @param callable $callback
* @return array
*/
public static function where($array, callable $callback)
{
return array_filter($array, $callback, ARRAY_FILTER_USE_BOTH);
}
/**
* Filter items where the value is not null.
*
* @param array $array
* @return array
*/
public static function whereNotNull($array)
{
return static::where($array, fn ($value) => ! is_null($value));
}
/**
* If the given value is not an array and not null, wrap it in one.
*
* @param mixed $value
* @return array
*/
public static function wrap($value)
{
if (is_null($value)) {
return [];
}
return is_array($value) ? $value : [$value];
}
}