WooCommerce Code Reference

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.
group_by_column()  : array<string|int, mixed>
Given an array of associative arrays, all having a shared key name ("column"), generates a new array in which keys are the distinct column values found, and values are arrays with all the matches found (or only the last matching array found, if $single_values is true).
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_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> &$items, string $key[, bool $throw_if_existing_is_not_array = false ]) : bool
Parameters
$items : 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
throws
Exception

The key already exists in the array but the value is not an array.

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> $items, string $key[, mixed $default_value = null ]) : mixed

E.g. for [ 'foo' => [ 'bar' => [ 'fizz' => 'buzz' ] ] ] the value for key 'foo::bar::fizz' would be 'buzz'.

Parameters
$items : array<string|int, mixed>

The array to get the value from.

$key : string

The complete key hierarchy, using '::' as separator.

$default_value : mixed = null

The value to return if the key doesn't exist in the array.

Tags
throws
Exception

$array is not an array.

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> $items, string $key[, null $default_value = 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
$items : array<string|int, mixed>

The array to get the value from.

$key : string

The key to use to retrieve the value.

$default_value : 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.

group_by_column()

Given an array of associative arrays, all having a shared key name ("column"), generates a new array in which keys are the distinct column values found, and values are arrays with all the matches found (or only the last matching array found, if $single_values is true).

public static group_by_column(array<string|int, mixed> $items, string $column[, bool $single_values = false ]) : array<string|int, mixed>

See ArrayUtilTest for examples.

Parameters
$items : array<string|int, mixed>

The array to process.

$column : string

The name of the key to group by.

$single_values : bool = false

True to only return the last suitable array found for each column value.

Return values
array<string|int, mixed> — The grouped array.

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> $items, string $key) : bool
Parameters
$items : 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> &$items, mixed $value) : bool
Parameters
$items : 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.

Return values
Closure — Callback to select the value.