ArrayUtil
in package
A class of utilities for dealing with arrays.
Table of Contents
- SELECT_BY_ARRAY_KEY = 3
- Array key selector type for the 'select' method.
- SELECT_BY_AUTO = 0
- Automatic selector type for the 'select' method.
- SELECT_BY_OBJECT_METHOD = 1
- Object method selector type for the 'select' method.
- SELECT_BY_OBJECT_PROPERTY = 2
- Object property selector type for the 'select' method.
- deep_assoc_array_diff() : array<string|int, mixed>
- Computes difference between two assoc arrays recursively. Similar to PHP's native assoc_array_diff, but also supports nested arrays.
- deep_compare_array_diff() : bool
- Returns whether two assoc array are same. The comparison is done recursively by keys, and the functions returns on first difference found.
- ensure_key_is_array() : bool
- Ensure that an associative array has a given key, and if not, set the key to an empty array.
- get_nested_value() : mixed
- Get a value from an nested array by specifying the entire key hierarchy with '::' as separator.
- get_value_or_default() : mixed|null
- Gets the value for a given key from an array, or a default value if the key doesn't exist in the array.
- is_truthy() : bool
- Checks if a given key exists in an array and its value can be evaluated as 'true'.
- push_once() : bool
- Push a value to an array, but only if the value isn't in the array already.
- select() : array<string|int, mixed>
- Select one single value from all the items in an array of either arrays or objects based on a selector.
- select_as_assoc() : array<string|int, mixed>
- Returns a new assoc array with format [ $key1 => $item1, $key2 => $item2, ... ] where $key is the value of the selector and items are original items passed.
- to_ranges_string() : string
- Converts an array of numbers to a human-readable range, such as "1,2,3,5" to "1-3, 5". It also supports floating point numbers, however with some perhaps unexpected / undefined behaviour if used within a range.
- deep_compute_or_compare_array_diff() : array<string|int, mixed>|bool
- Helper method to compare to compute difference between two arrays. Comparison is done recursively.
- get_selector_callback() : Closure
- Helper function to generate a callback which can be executed on an array to select a value from each item.
Constants
SELECT_BY_ARRAY_KEY
Array key selector type for the 'select' method.
public
mixed
SELECT_BY_ARRAY_KEY
= 3
SELECT_BY_AUTO
Automatic selector type for the 'select' method.
public
mixed
SELECT_BY_AUTO
= ""
SELECT_BY_OBJECT_METHOD
Object method selector type for the 'select' method.
public
mixed
SELECT_BY_OBJECT_METHOD
= 1
SELECT_BY_OBJECT_PROPERTY
Object property selector type for the 'select' method.
public
mixed
SELECT_BY_OBJECT_PROPERTY
= 2
Methods
deep_assoc_array_diff()
Computes difference between two assoc arrays recursively. Similar to PHP's native assoc_array_diff, but also supports nested arrays.
public
static deep_assoc_array_diff(array<string|int, mixed> $array1, array<string|int, mixed> $array2[, bool $strict = true ]) : array<string|int, mixed>
Parameters
- $array1 : array<string|int, mixed>
-
First array.
- $array2 : array<string|int, mixed>
-
Second array.
- $strict : bool = true
-
Whether to also match type of values.
Return values
array<string|int, mixed> — The difference between the two arrays.deep_compare_array_diff()
Returns whether two assoc array are same. The comparison is done recursively by keys, and the functions returns on first difference found.
public
static deep_compare_array_diff(array<string|int, mixed> $array1, array<string|int, mixed> $array2[, bool $strict = true ]) : bool
Parameters
- $array1 : array<string|int, mixed>
-
First array to compare.
- $array2 : array<string|int, mixed>
-
Second array to compare.
- $strict : bool = true
-
Whether to use strict comparison.
Return values
bool — Whether the arrays are different.ensure_key_is_array()
Ensure that an associative array has a given key, and if not, set the key to an empty array.
public
static ensure_key_is_array(array<string|int, mixed> &$array, string $key[, bool $throw_if_existing_is_not_array = false ]) : bool
Parameters
- $array : array<string|int, mixed>
-
The array to check.
- $key : string
-
The key to check.
- $throw_if_existing_is_not_array : bool = false
-
If true, an exception will be thrown if the key already exists in the array but the value is not an array.
Tags
Return values
bool — True if the key has been added to the array, false if not (the key already existed).get_nested_value()
Get a value from an nested array by specifying the entire key hierarchy with '::' as separator.
public
static get_nested_value(array<string|int, mixed> $array, string $key[, mixed $default = null ]) : mixed
E.g. for [ 'foo' => [ 'bar' => [ 'fizz' => 'buzz' ] ] ] the value for key 'foo::bar::fizz' would be 'buzz'.
Parameters
- $array : array<string|int, mixed>
-
The array to get the value from.
- $key : string
-
The complete key hierarchy, using '::' as separator.
- $default : mixed = null
-
The value to return if the key doesn't exist in the array.
Tags
Return values
mixed — The retrieved value, or the supplied default value.get_value_or_default()
Gets the value for a given key from an array, or a default value if the key doesn't exist in the array.
public
static get_value_or_default(array<string|int, mixed> $array, string $key[, null $default = null ]) : mixed|null
This is equivalent to "$array[$key] ?? $default" except in one case: when they key exists, has a null value, and a non-null default is supplied:
$array = ['key' => null] $array['key'] ?? 'default' => 'default' ArrayUtil::get_value_or_default($array, 'key', 'default') => null
Parameters
- $array : array<string|int, mixed>
-
The array to get the value from.
- $key : string
-
The key to use to retrieve the value.
- $default : null = null
-
The default value to return if the key doesn't exist in the array.
Return values
mixed|null — The value for the key, or the default value passed.is_truthy()
Checks if a given key exists in an array and its value can be evaluated as 'true'.
public
static is_truthy(array<string|int, mixed> $array, string $key) : bool
Parameters
- $array : array<string|int, mixed>
-
The array to check.
- $key : string
-
The key for the value to check.
Return values
bool — True if the key exists in the array and the value can be evaluated as 'true'.push_once()
Push a value to an array, but only if the value isn't in the array already.
public
static push_once(array<string|int, mixed> &$array, mixed $value) : bool
Parameters
- $array : array<string|int, mixed>
-
The array.
- $value : mixed
-
The value to maybe push.
Return values
bool — True if the value has been added to the array, false if the value was already in the array.select()
Select one single value from all the items in an array of either arrays or objects based on a selector.
public
static select(array<string|int, mixed> $items, string $selector_name[, int $selector_type = self::SELECT_BY_AUTO ]) : array<string|int, mixed>
For arrays, the selector is a key name; for objects, the selector can be either a method name or a property name.
Parameters
- $items : array<string|int, mixed>
-
Items to apply the selection to.
- $selector_name : string
-
Key, method or property name to use as a selector.
- $selector_type : int = self::SELECT_BY_AUTO
-
Selector type, one of the SELECT_BY_* constants.
Return values
array<string|int, mixed> — The selected values.select_as_assoc()
Returns a new assoc array with format [ $key1 => $item1, $key2 => $item2, ... ] where $key is the value of the selector and items are original items passed.
public
static select_as_assoc(array<string|int, mixed> $items, string $selector_name[, int $selector_type = self::SELECT_BY_AUTO ]) : array<string|int, mixed>
Parameters
- $items : array<string|int, mixed>
-
Items to use for conversion.
- $selector_name : string
-
Key, method or property name to use as a selector.
- $selector_type : int = self::SELECT_BY_AUTO
-
Selector type, one of the SELECT_BY_* constants.
Return values
array<string|int, mixed> — The converted assoc array.to_ranges_string()
Converts an array of numbers to a human-readable range, such as "1,2,3,5" to "1-3, 5". It also supports floating point numbers, however with some perhaps unexpected / undefined behaviour if used within a range.
public
static to_ranges_string(array<string|int, mixed> $items[, string $item_separator = ', ' ][, string $range_separator = '-' ][, bool|true $sort = true ]) : string
Source: https://stackoverflow.com/a/34254663/4574
Parameters
- $items : array<string|int, mixed>
-
An array (in any order, see $sort) of individual numbers.
- $item_separator : string = ', '
-
The string that separates sequential range groups. Defaults to ', '.
- $range_separator : string = '-'
-
The string that separates ranges. Defaults to '-'. A plausible example otherwise would be ' to '.
- $sort : bool|true = true
-
Sort the array prior to iterating? You'll likely always want to sort, but if not, you can set this to false.
Return values
string —deep_compute_or_compare_array_diff()
Helper method to compare to compute difference between two arrays. Comparison is done recursively.
private
static deep_compute_or_compare_array_diff(array<string|int, mixed> $array1, array<string|int, mixed> $array2, bool $compare[, bool $strict = true ]) : array<string|int, mixed>|bool
Parameters
- $array1 : array<string|int, mixed>
-
First array.
- $array2 : array<string|int, mixed>
-
Second array.
- $compare : bool
-
Whether to compare the arrays. If true, then function will return false on first difference, in order to be slightly more efficient.
- $strict : bool = true
-
Whether to do string comparison.
Return values
array<string|int, mixed>|bool — The difference between the two arrays, or if array are same, depending upon $compare param.get_selector_callback()
Helper function to generate a callback which can be executed on an array to select a value from each item.
private
static get_selector_callback(string $selector_name[, int $selector_type = self::SELECT_BY_AUTO ]) : Closure
Parameters
- $selector_name : string
-
Field/property/method name to select.
- $selector_type : int = self::SELECT_BY_AUTO
-
Selector type.