Craft 4 Class Reference

ArrayHelper

Type
Class
Namespace
craft\helpers
Inherits
craft\helpers\ArrayHelper » yii\helpers\ArrayHelper (opens new window) » yii\helpers\BaseArrayHelper (opens new window)
Since
3.0.0

Class ArrayHelper

View source (opens new window)

# Public Methods

Method Description
append() Appends values to an array.
contains() Returns whether the given array contains any values where a given key (the name of a sub-array key or sub-object property) is set to a given value.
containsRecursive() Returns whether the given array, or any nested arrays, contain any values where a given key (the name of a sub-array key or sub-object property) is set to a given value.
ensureNonAssociative() Ensures an array is non-associative.
filter() (opens new window) Filters array according to rules specified.
filterEmptyStringsFromArray() Filters empty strings from an array.
firstKey() Returns the first key in a given array.
firstValue() Returns the first value in a given array.
firstWhere() Returns the first value in a given array where a given key (the name of a sub-array key or sub-object property) is set to a given value.
getColumn() (opens new window) Returns the values of a specified column in an array.
getValue() Retrieves the value of an array element or object property with the given key or property name.
htmlDecode() (opens new window) Decodes HTML entities into the corresponding characters in an array of strings.
htmlEncode() (opens new window) Encodes special characters in an array of strings into HTML entities.
index() (opens new window) Indexes and/or groups the array according to a specified key.
isAssociative() (opens new window) Returns a value indicating whether the given array is an associative array.
isIn() (opens new window) Check whether an array or Traversable (opens new window) contains an element.
isIndexed() (opens new window) Returns a value indicating whether the given array is an indexed array.
isNumeric() Returns whether all the elements in the array are numeric.
isOrdered() Checks whether a numerically-indexed array's keys are in ascending order.
isSubset() (opens new window) Checks whether an array or Traversable (opens new window) is a subset of another array or Traversable (opens new window).
isTraversable() (opens new window) Checks whether a variable is an array or Traversable (opens new window).
keyExists() (opens new window) Checks if the given array contains the specified key.
map() (opens new window) Builds a map (key-value pairs) from a multidimensional array or an array of objects.
merge() (opens new window) Merges two or more arrays into one recursively.
multisort() (opens new window) Sorts an array of objects or arrays (with the same structure) by one or several keys.
onlyContains() Returns whether the given array contains only values where a given key (the name of a -ub-array key or sub-object property) is sett o given value.
prepend() Prepends values to an array.
prependOrAppend() Prepends or appends a value to an array.
recursiveSort() (opens new window) Sorts array recursively.
remove() (opens new window) Removes an item from an array and returns the value. If the key does not exist in the array, the default value will be returned instead.
removeValue() Removes items with matching values from the array and returns the removed items.
rename() Renames an item in an array. If the new key already exists in the array and the old key doesn’t, the array will be left unchanged.
setValue() (opens new window) Writes a value into an associative array at the key path specified.
toArray() Converts an object or an array of objects into an array.
where() Filters an array to only the values where a given key (the name of a sub-array key or sub-object property) is set to a given value.
whereIn() Filters an array to only the values where a given key (the name of a sub-array key or sub-object property) is set to one of a given range of values.
whereMultiple() Filters an array to only the values where a list of keys is set to given values.
without() Returns a copy of an array without a given key.
withoutValue() Returns a copy of an array without items matching the given value.

# append()

DEPRECATED

Deprecated in 4.0.0. array_push() should be used instead.

Since
3.4.0

Appends values to an array.

View source (opens new window)

Arguments

Example

ArrayHelper::append($array, ...$values);

# contains()

Since
3.4.0

Returns whether the given array contains any values where a given key (the name of a sub-array key or sub-object property) is set to a given value.

View source (opens new window)

Arguments

  • $array (iterable) – The array that the value will be searched for in
  • $key (callable (opens new window), string (opens new window)) – The column name or anonymous function which must be set to $value
  • $value (mixed) – The value that $key should be compared with
  • $strict (boolean (opens new window)) – Whether a strict type comparison should be used when checking array element values against $value

Returns

boolean (opens new window) – Whether the value exists in the array

# containsRecursive()

Since
4.4.10

Returns whether the given array, or any nested arrays, contain any values where a given key (the name of a sub-array key or sub-object property) is set to a given value.

View source (opens new window)

Arguments

  • $array (iterable) – The array that the value will be searched for in
  • $key (callable (opens new window), string (opens new window)) – The column name or anonymous function which must be set to $value
  • $value (mixed) – The value that $key should be compared with
  • $strict (boolean (opens new window)) – Whether a strict type comparison should be used when checking array element values against $value

Returns

boolean (opens new window) – Whether the value exists in the array, recursively

# ensureNonAssociative()

Since
3.1.17.1

Ensures an array is non-associative.

View source (opens new window)

Arguments

# filterEmptyStringsFromArray()

Filters empty strings from an array.

View source (opens new window)

Arguments

Returns

array (opens new window)

# firstKey()

DEPRECATED

Deprecated in 4.5.0. array_key_first() should be used instead.

Returns the first key in a given array.

View source (opens new window)

Arguments

Returns

string (opens new window), integer (opens new window), null (opens new window) – The first key, whether that is a number (if the array is numerically indexed) or a string, or null if $array isn’t an array, or is empty.

# firstValue()

Returns the first value in a given array.

View source (opens new window)

Arguments

Returns

mixed – The first value, or null if $array isn’t an array, or is empty.

# firstWhere()

Since
3.1.0

Returns the first value in a given array where a given key (the name of a sub-array key or sub-object property) is set to a given value.

View source (opens new window)

Arguments

  • $array (iterable) – The array that the value will be searched for in
  • $key (callable (opens new window), string (opens new window)) – The column name or anonymous function which must be set to $value
  • $value (mixed) – The value that $key should be compared with
  • $strict (boolean (opens new window)) – Whether a strict type comparison should be used when checking array element values against $value

Returns

mixed – The value, or null if it can't be found

# getValue()

Retrieves the value of an array element or object property with the given key or property name.

If the key does not exist in the array, the default value will be returned instead. Not used when getting value from an object.

The key may be specified in a dot format to retrieve the value of a sub-array or the property of an embedded object. In particular, if the key is x.y.z, then the returned value would be $array['x']['y']['z'] or $array->x->y->z (if $array is an object). If $array['x'] or $array->x is neither an array nor an object, the default value will be returned. Note that if the array already has an element x.y.z, then its value will be returned instead of going through the sub-arrays. So it is better to be done specifying an array of key names like ['x', 'y', 'z'].

Below are some usage examples,

// working with array
$username = \yii\helpers\ArrayHelper::getValue($_POST, 'username');
// working with object
$username = \yii\helpers\ArrayHelper::getValue($user, 'username');
// working with anonymous function
$fullName = \yii\helpers\ArrayHelper::getValue($user, function ($user, $defaultValue) {
    return $user->firstName . ' ' . $user->lastName;
});
// using dot format to retrieve the property of embedded object
$street = \yii\helpers\ArrayHelper::getValue($users, 'address.street');
// using an array of keys to retrieve the value
$value = \yii\helpers\ArrayHelper::getValue($versions, ['1.0', 'date']);

If the key is specified in square bracket notation (e.g. x[y][z]), it will automatically be converted to dot notation (x.y.z).

View source (opens new window)

Arguments

Returns

mixed – The value of the element if found, default value otherwise

# isNumeric()

Since
3.5.0

Returns whether all the elements in the array are numeric.

View source (opens new window)

Arguments

Returns

boolean (opens new window)

# isOrdered()

Since
3.4.0

Checks whether a numerically-indexed array's keys are in ascending order.

View source (opens new window)

Arguments

Returns

boolean (opens new window)

# onlyContains()

Since
3.7.38

Returns whether the given array contains only values where a given key (the name of a -ub-array key or sub-object property) is sett o given value.

View source (opens new window)

Arguments

  • $array (iterable) – The array that the value will be searched for in
  • $key (callable (opens new window), string (opens new window)) – The column name or anonymous function which must be set to $value
  • $value (mixed) – The value that $key should be compared with
  • $strict (boolean (opens new window)) – Whether a strict type comparison should be used when checking array element values against $value

Returns

boolean (opens new window) – Whether the value exists in the array

# prepend()

DEPRECATED

Deprecated in 4.0.0. array_unshift() should be used instead.

Since
3.4.0

Prepends values to an array.

View source (opens new window)

Arguments

Example

ArrayHelper::prepend($array, ...$values);

# prependOrAppend()

Prepends or appends a value to an array.

View source (opens new window)

Arguments

# removeValue()

Since
4.2.0

Removes items with matching values from the array and returns the removed items.

Example,

$array = ['Bob' => 'Dylan', 'Michael' => 'Jackson', 'Mick' => 'Jagger', 'Janet' => 'Jackson'];
$removed = \yii\helpers\ArrayHelper::removeValue($array, 'Jackson');
// result:
// $array = ['Bob' => 'Dylan', 'Mick' => 'Jagger'];
// $removed = ['Michael' => 'Jackson', 'Janet' => 'Jackson'];

View source (opens new window)

Arguments

  • $array (array (opens new window)) – The array where to look the value from
  • $value (mixed) – The value to remove from the array
  • $strict (boolean (opens new window)) – Whether a strict type comparison should be used when checking array element values against $value

Returns

array (opens new window) – The items that were removed from the array

# rename()

Renames an item in an array. If the new key already exists in the array and the old key doesn’t, the array will be left unchanged.

View source (opens new window)

Arguments

# toArray()

Converts an object or an array of objects into an array.

View source (opens new window)

Arguments

[
    'app\models\Post' => [
        'id',
        'title',
        // the key name in array result => property name
        'createTime' => 'created_at',
        // the key name in array result => anonymous function
        'length' => function ($post) {
            return strlen($post->content);
        },
    ],
]

The result of ArrayHelper::toArray($post, $properties) could be like the following:

[
    'id' => 123,
    'title' => 'test',
    'createTime' => '2013-01-01 12:00AM',
    'length' => 301,
]

Returns

array (opens new window) – The array representation of the object

# where()

Filters an array to only the values where a given key (the name of a sub-array key or sub-object property) is set to a given value.

Array keys are preserved by default.

View source (opens new window)

Arguments

  • $array (iterable) – The array that needs to be indexed or grouped
  • $key (callable (opens new window), string (opens new window)) – The column name or anonymous function which result will be used to index the array
  • $value (mixed) – The value that $key should be compared with
  • $strict (boolean (opens new window)) – Whether a strict type comparison should be used when checking array element values against $value
  • $keepKeys (boolean (opens new window)) – Whether to maintain the array keys. If false, the resulting array will be re-indexed with integers.

Returns

array (opens new window) – The filtered array

# whereIn()

Since
3.5.8

Filters an array to only the values where a given key (the name of a sub-array key or sub-object property) is set to one of a given range of values.

Array keys are preserved by default.

View source (opens new window)

Arguments

Returns

array (opens new window) – The filtered array

# whereMultiple()

Since
3.3.0

Filters an array to only the values where a list of keys is set to given values.

Array keys are preserved.

This method is most useful when, given an array of elements, it is needed to filter them by multiple conditions.

Below are some usage examples,

// Entries with certain entry types
$filtered = \craft\helpers\ArrayHelper::whereMultiple($entries, ['typeId' => [2, 4]]);

// Entries with multiple conditions
$filtered = \craft\helpers\ArrayHelper::whereMultiple($entries, ['typeId' => 2, 'authorId' => [1, 2]);

// Testing for an array value
$filtered = \craft\helpers\ArrayHelper::whereMultiple($asset, ['focalPoint' => [['x' => 0.5, 'y' => 0.5]]]);

View source (opens new window)

Arguments

  • $array (iterable) – The array that needs to be indexed or grouped
  • $conditions (array (opens new window)) – An array of key/value pairs of allowed values. Values can be arrays to allow multiple values.
  • $strict (boolean (opens new window)) – Whether a strict type comparison should be used when checking array element values against $value

Returns

array (opens new window) – The filtered array

# without()

Since
3.0.9

Returns a copy of an array without a given key.

View source (opens new window)

Arguments

Returns

array (opens new window)

# withoutValue()

Returns a copy of an array without items matching the given value.

View source (opens new window)

Arguments

Returns

array (opens new window)

← Assets →