Array Helper

ArrayHelper::get()

/**
 * Gets a dot-notated key from an array, with a default value if it does
 * not exist.
 *
 * @param array|ArrayAccess $array $array The search array.
 * @param mixed|null $key The dot-notated key or array of keys.
 * @param string|null $default The default value
 * @return mixed
 * @throws TypeException
 */
public function get(array|ArrayAccess $array, mixed $key = null, ?string $default = null): mixed;

ArrayHelper::set()

/**
 * Set an array item (dot-notated) to the value.
 *
 * @param array   $array  The array to insert it into
 * @param mixed   $key    The dot-notated key to set or array of keys
 * @param mixed|null $value  The value
 * @return void
 */
public function set(array &$array, mixed $key, mixed $value = null): void;

ArrayHelper::pluck()

/**
 * Pluck an array of values from an array.
 *
 * @param array $array Collection of arrays to pluck from.
 * @param string $key Key of the value to pluck.
 * @param bool|int|string|null $index Optional return array index key, true for original index.
 * @return array Array of plucked values.
 * @throws TypeException
 */
public function pluck(array $array, string $key, bool|int|string $index = null): array;

ArrayHelper::keyExists()

/**
 * Array_key_exists with a dot-notated key from an array.
 *
 * @param array|ArrayAccess $array $array The search array
 * @param mixed $key The dot-notated key or array of keys
 * @return bool
 * @throws TypeException
 */
public function keyExists(array|ArrayAccess $array, mixed $key): bool;

ArrayHelper::delete()

/**
 * Unsets dot-notated k?string ey from an array
 *
 * @param array   $array    The search array
 * @param mixed|null $key   The dot-notated key or array of keys
 * @return mixed
 */
public function delete(array &$array, mixed $key = null): mixed;

ArrayHelper::assocToKeyVal()

/**
 * Converts a multidimensional associative array into an array of key => values with the provided field names.
 *
 * @param array|Iterator $assoc The array to convert.
 * @param string $keyField The field name of the key field.
 * @param string $valField The field name of the value field.
 * @return array
 * @throws TypeException
 */
public function assocToKeyVal(array|Iterator $assoc, string $keyField, string $valField): array;

ArrayHelper::keyValToAssoc()

/**
 * Converts an array of key => values into a multidimensional associative array with the provided field names
 *
 * @param array|Iterator $array $array      the array to convert
 * @param string $keyField the field name of the key field
 * @param string $valField the field name of the value field
 * @return  array
 * @throws TypeException
 */
public function keyValToAssoc(array|Iterator $array, string $keyField, string $valField): array;

ArrayHelper::toAssoc()

/**
 * Converts the given 1 dimensional non-associative array to an associative
 * array.
 *
 * The array given must have an even number of elements or null will be returned.
 *
 *     $this->toAssoc(['foo','bar']);
 *
 * @param array      $arr  the array to change
 * @return  array|null  the new array or null
 * @throws BadMethodCallException
 */
public function toAssoc(array $arr): ?array;

ArrayHelper::isAssoc()

/**
 * Checks if the given array is an assoc array.
 *
 * @param array $arr the array to check
 * @return bool True if it's an assoc array, false if not.
 */
public function isAssoc(array $arr): bool;

ArrayHelper::flatten()

/**
 * Flattens a multi-dimensional associative array down into a 1 dimensional
 * associative array.
 *
 * @param array   $array   the array to flatten
 * @param string  $glue    what to glue the keys together with
 * @param bool    $reset   whether to reset and start over on a new array
 * @param bool    $indexed whether to flatten only associative array's, or also indexed ones
 * @return array
 */
public function flatten(array $array, string $glue = ':', bool $reset = true, bool $indexed = true): array;

ArrayHelper::flattenAssoc()

/**
 * Flattens a multi-dimensional associative array down into a 1 dimensional
 * associative array.
 *
 * @param array   $array  the array to flatten
 * @param string  $glue   what to glue the keys together with
 * @param bool    $reset  whether to reset and start over on a new array
 * @return array
 */
public function flattenAssoc(array $array, string $glue = ':', bool $reset = true): array;

ArrayHelper::reverseFlatten()

/**
 * Reverse a flattened array in its original form.
 *
 * @param array   $array  flattened array
 * @param string  $glue   glue used in flattening
 * @return array The unflattened array.
 */
public function reverseFlatten(array $array, string $glue = ':'): array;

ArrayHelper::filterPrefixed()

/**
 * Filters an array on prefixed associative keys.
 *
 * @param array   $array        The array to filter.
 * @param string  $prefix       Prefix to filter on.
 * @param bool    $removePrefix Whether to remove the prefix.
 * @return array
 */
public function filterPrefixed(array $array, string $prefix, bool $removePrefix = true): array;

ArrayHelper::filterRecursive()

/**
 * Recursive version of PHP's array_filter().
 *
 * @param array $array The array to filter.
 * @param callable|null $callback $callback The callback that determines whether a value is filtered.
 * @return array
 */
public function filterRecursive(array $array, ?callable $callback = null): array;

ArrayHelper::removePrefixed()

/**
 * Removes items from an array that match a key prefix.
 *
 * @param array  $array  The array to remove from.
 * @param string $prefix Prefix to filter on.
 * @return array
 */
public function removePrefixed(array $array, string $prefix): array;

ArrayHelper::filterSuffixed()

/**
 * Filters an array on suffixed associative keys.
 *
 * @param array  $array        The array to filter.
 * @param string $suffix       Suffix to filter on.
 * @param bool   $removeSuffix Whether to remove the suffix.
 * @return array
 */
public function filterSuffixed(array $array, string $suffix, bool $removeSuffix = true): array;

ArrayHelper::removeSuffixed()

/**
 * Removes items from an array that match a key suffix.
 *
 * @param array  $array  The array to remove from.
 * @param string $suffix Suffix to filter on.
 * @return array
 */
public function removeSuffixed(array $array, string $suffix): array;

ArrayHelper::filterKeys()

/**
 * Filters an array by an array of keys
 *
 * @param array  $array  The array to filter.
 * @param array  $keys   The keys to filter
 * @param bool   $remove If true, removes the matched elements.
 * @return array
 */
public function filterKeys(array $array, array $keys, bool $remove = false): array;

ArrayHelper::insert()

/**
 * Insert value(s) into an array, mostly an array_splice alias.
 *
 * WARNING: original array is edited by reference, only bool success is returned.
 *
 * @param array $original The original array (by reference).
 * @param mixed $value    The value(s) to insert, if you want to insert an array
 *                        it needs to be in an array itself.
 * @param int   $pos      The numeric position at which to insert, negative to count from the end backwards.
 * @return bool False when array shorter than $pos, otherwise true
 */
public function insert(array &$original, mixed $value, int $pos): bool;

ArrayHelper::insertAssoc()

/**
 * Insert value(s) into an array, mostly an array_splice alias
 * WARNING: original array is edited by reference, only bool success is returned
 *
 * @param array $original The original array (by reference)
 * @param mixed $values   The value(s) to insert, if you want to insert an array
 *                        it needs to be in an array itself.
 * @param int   $pos      The numeric position at which to insert, negative to count from the end backwards.
 * @return bool false when array shorter than $pos, otherwise true
 */
public function insertAssoc(array &$original, mixed $values, int $pos): bool;

ArrayHelper::insertBeforeKey()

/**
 * Insert value(s) into an array before a specific key.
 *
 * WARNING: original array is edited by reference, only bool success is returned.
 *
 * @param array      $original The original array (by reference).
 * @param mixed      $value    The value(s) to insert, if you want to insert an array
 *                             it needs to be in an array itself.
 * @param int|string $key      The key before which to insert.
 * @param bool       $isAssoc  Whether the input is an associative array.
 * @return bool False when key isn't found in the array, otherwise true.
 */
public function insertBeforeKey(array &$original, mixed $value, int|string $key, bool $isAssoc = false): bool;

ArrayHelper::insertAfterKey()

/**
 * Insert value(s) into an array after a specific key.
 *
 * WARNING: original array is edited by reference, only bool success is returned.
 *
 * @param array      $original The original array (by reference).
 * @param mixed      $value    The value(s) to insert, if you want to insert an array
 *                             it needs to be in an array itself.
 * @param int|string $key      The key after which to insert.
 * @param bool       $isAssoc  Whether the input is an associative array.
 * @return bool False when key isn't found in the array, otherwise true.
 */
public function insertAfterKey(array &$original, mixed $value, int|string $key, bool $isAssoc = false): bool;

ArrayHelper::insertAfterValue()

/**
 * Insert value(s) into an array after a specific value (first found in array).
 *
 * @param array      $original The original array (by reference).
 * @param mixed      $value    The value(s) to insert, if you want to insert an array
 *                             it needs to be in an array itself.
 * @param int|string $search   The value after which to insert.
 * @param bool       $isAssoc  Whether the input is an associative array.
 * @return bool False when value isn't found in the array, otherwise true.
 */
public function insertAfterValue(array &$original, mixed $value, int|string $search, bool $isAssoc = false): bool;

ArrayHelper::insertBeforeValue()

/**
 * Insert value(s) into an array before a specific value (first found in array)
 *
 * @param array      $original The original array (by reference).
 * @param mixed      $value    The value(s) to insert, if you want to insert an array.
 *                             it needs to be in an array itself.
 * @param int|string $search   The value after which to insert.
 * @param bool       $isAssoc  Whether the input is an associative array.
 * @return bool False when value isn't found in the array, otherwise true.
 */
public function insertBeforeValue(array &$original, mixed $value, int|string $search, bool $isAssoc = false): bool;

ArrayHelper::sort()

/**
 * Sorts a multi-dimensional array by it's values.
 *
 * @param array $array     The array to fetch from.
 * @param string $key       The key to sort by.
 * @param string $order     The order (asc or desc).
 * @param int    $sortFlags The php sort type flag.
 * @return array
 * @throws TypeException
 */
public function sort(
    array $array,
    string $key,
    string $order = 'asc',
    int $sortFlags = SORT_REGULAR
): array;

ArrayHelper::multisort()

/**
 * Sorts an array on multiple values, with deep sorting support.
 *
 * @param array $array Collection of arrays/objects to sort.
 * @param array $conditions Sorting conditions.
 * @param bool $ignoreCase Whether to sort case-insensitive.
 * @return array
 * @throws TypeException
 */
public function multisort(array $array, array $conditions, bool $ignoreCase = false): array;

ArrayHelper::average()

/**
 * Find the average of an array.
 *
 * @param array $array The array containing the values.
 * @return float|int The average value.
 */
public function average(array $array): float|int;

ArrayHelper::replaceKey()

/**
 * Replaces key names in an array by names in the $replace parameter.
 *
 * @param array $source The array containing the key/value combinations
 * @param array|string $replace Key to replace or array containing the replacement keys
 * @param string|null $newKey The replacement key
 * @return array The array with the new keys.
 */
public function replaceKey(array $source, array|string $replace, ?string $newKey = null): array;

ArrayHelper::merge()

/**
 * Merge 2 arrays recursively, differs in 2 important ways from array_merge_recursive().
 *
 * When there's 2 different values and not both arrays, the latter value overwrites the earlier
 * instead of merging both into an array.
 *
 * Numeric keys that don't conflict aren't changed, only when a numeric key already exists is the
 * value added using array_push().
 *
 * @return array
 * @throws TypeException
 */
public function merge(): array;

ArrayHelper::mergeAssoc()

/**
 * Merge 2 arrays recursively, differs in 2 important ways from array_merge_recursive().
 *
 * When there's 2 different values and not both arrays, the latter value overwrites the earlier
 * instead of merging both into an array. Numeric keys are never changed.
 *
 * @return array
 * @throws TypeException
 */
public function mergeAssoc(): array;

ArrayHelper::prepend()

/**
 * Prepends a value with an associative key to an array.
 *
 * Will overwrite if the value exists.
 *
 * @param array        $arr   The array to prepend to
 * @param array|string $key   The key or array of keys and values
 * @param mixed|null $value The value to prepend
 */
public function prepend(array &$arr, array|string $key, mixed $value = null): string|array;

ArrayHelper::inArrayRecursive()

/**
 * Recursive in_array
 *
 * @param mixed $needle   What to search for.
 * @param array $haystack Array to search in.
 * @return bool Whether the needle is found in the haystack.
 */
public function inArrayRecursive(mixed $needle, array $haystack, bool $strict = false): bool;

ArrayHelper::isMulti()

/**
 * Checks if the given array is a multidimensional array.
 *
 * @param array $arr     The array to check
 * @param bool  $allKeys If true, check that all elements are arrays.
 * @return bool True if its a multidimensional array, false if not.
 */
public function isMulti(array $arr, bool $allKeys = false): bool;

ArrayHelper::search()

/**
 * Searches the array for a given value and returns the
 * corresponding key or default value.
 *
 * If $recursive is set to true, then the $this->search()
 * method will return a delimiter-notated key using the
 * $delimiter parameter.
 *
 * @param array|ArrayAccess $array $array     The search array.
 * @param mixed $value The searched value.
 * @param string|null $default The default value.
 * @param bool $recursive Whether to get keys recursive.
 * @param string $delimiter The delimiter, when $recursive is true.
 * @param bool $strict If true, do a strict key comparison.
 * @return string|bool|null
 * @throws TypeException
 */
public function search(
    array|ArrayAccess $array,
    mixed $value,
    ?string $default = null,
    bool $recursive = true,
    string $delimiter = '.',
    bool $strict = false
): string|bool|null;

ArrayHelper::unique()

/**
 * Returns only unique values in an array. It does not sort. First value is used.
 *
 * @param array $arr The array to dedupe.
 * @return array array With only de-duped values.
 */
public function unique(array $arr): array;

ArrayHelper::sum()

/**
 * Calculate the sum of an array.
 *
 * @param array|ArrayAccess $array $array The array containing the values.
 * @param string $key Key of the value to pluck.
 * @return float|int The sum value
 * @throws TypeException
 */
public function sum(array|ArrayAccess $array, string $key): float|int;

ArrayHelper::reindex()

/**
 * Returns the array with all numeric keys re-indexed, and string keys untouched.
 *
 * @param array $arr The array to reindex.
 * @return array Re-indexed array.
 */
public function reindex(array $arr): array;

ArrayHelper::previousByKey()

/**
 * Get the previous value or key from an array using the current array key.
 *
 * @param array|ArrayAccess $array $array    The array containing the values.
 * @param string $key Key of the current entry to use as reference.
 * @param bool $getValue If true, return the previous value instead of the previous key.
 * @param bool $strict If true, do a strict key comparison.
 * @return string|bool|null The value in the array, null if there is no previous value,
 *                          or false if the key doesn't exist.
 * @throws TypeException
 */
public function previousByKey(
    array|ArrayAccess $array,
    string $key,
    bool $getValue = false,
    bool $strict = false
): string|bool|null;

ArrayHelper::nextByKey()

/**
 * Get the next value or key from an array using the current array key.
 *
 * @param array|ArrayAccess $array $array The array containing the values.
 * @param string $key Key of the current entry to use as reference.
 * @param bool $getValue If true, return the next value instead of the next key.
 * @param bool $strict If true, do a strict key comparison.
 * @return string|bool|null The value in the array, null if there is no next value,
 *                          or false if the key doesn't exist.
 * @throws TypeException
 */
public function nextByKey(
    array|ArrayAccess $array,
    string $key,
    bool $getValue = false,
    bool $strict = false
): string|bool|null;

ArrayHelper::previousByValue()

/**
 * Get the previous value or key from an array using the current array value
 *
 * @param array|ArrayAccess $array $array    The array containing the values.
 * @param string $value Value of the current entry to use as reference.
 * @param bool $getValue If true, return the previous value instead of the previous key.
 * @param bool $strict If true, do a strict key comparison.
 * @return string|bool|null The value in the array, null if there is no previous value,
 *                          or false if the key doesn't exist.
 * @throws TypeException
 */
public function previousByValue(
    array|ArrayAccess $array,
    string $value,
    bool $getValue = true,
    bool $strict = false
): string|bool|null;

ArrayHelper::nextByValue()

/**
 * Get the next value or key from an array using the current array value.
 *
 * @param array|ArrayAccess $array $array    The array containing the values.
 * @param string $value Value of the current entry to use as reference.
 * @param bool $getValue If true, return the next value instead of the next key.
 * @param bool $strict If true, do a strict key comparison.
 * @return string|bool|null The value in the array, null if there is no next value,
 *                          or false if the key doesn't exist
 * @throws TypeException
 */
public function nextByValue(
    array|ArrayAccess $array,
    string $value,
    bool $getValue = true,
    bool $strict = false
): string|bool|null;

ArrayHelper::subset()

/**
 * Return the subset of the array defined by the supplied keys.
 *
 * Returns $default for missing keys, as with $this->get().
 *
 * @param array $array The array containing the values.
 * @param array $keys List of keys (or indices) to return.
 * @param mixed|null $default Value of missing keys; default null.
 * @return array An array containing the same set of keys provided.
 * @throws TypeException
 */
public function subset(array $array, array $keys, mixed $default = null): array;

ArrayHelper::value()

/**
 * Takes a value and checks if it is a Closure or not, if it is it
 * will return the result of the closure, if not, it will simply return the
 * value.
 *
 * @param mixed $var The value to get.
 * @return mixed
 */
public function value(mixed $var): mixed;