Craft 3 Class Reference

Appearance

ArrayHelper ​

Type
Class
Namespace
craft\helpers
Inherits
craft\helpers\ArrayHelper » yii\helpers\ArrayHelper » yii\helpers\BaseArrayHelper
Since
3.0.0

Class ArrayHelper

View source

Public Methods ​

MethodDescription
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.
ensureNonAssociative()Ensures an array is non-associative.
filter()Filters array according to rules specified.
filterByValue()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.
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()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()Decodes HTML entities into the corresponding characters in an array of strings.
htmlEncode()Encodes special characters in an array of strings into HTML entities.
index()Indexes and/or groups the array according to a specified key.
isAssociative()Returns a value indicating whether the given array is an associative array.
isIn()Check whether an array or Traversable contains an element.
isIndexed()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()Checks whether an array or Traversable is a subset of another array or Traversable.
isTraversable()Checks whether a variable is an array or Traversable.
keyExists()Checks if the given array contains the specified key.
map()Builds a map (key-value pairs) from a multidimensional array or an array of objects.
merge()Merges two or more arrays into one recursively.
multisort()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()Sorts array recursively.
remove()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()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() ​

Since
3.4.0

Appends values to an array.

This should be used instead of array_push($array, ...$values) when $values could be an empty array, as PHP < 7.3 would throw an error in that case.

View source

Arguments ​

  • $array (array) – The array to be appended to
  • $values (mixed) – The values to append.

Example ​

php
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

Arguments ​

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

Returns ​

boolean – Whether the value exists in the array

ensureNonAssociative() ​

Since
3.1.17.1

Ensures an array is non-associative.

View source

Arguments ​

filterByValue() ​

DEPRECATED

Deprecated in 3.2.0. Use where() instead.

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.

View source

Arguments ​

  • $array (array, Traversable) – The array that needs to be indexed or grouped
  • $key (string, Closure) – 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) – Whether a strict type comparison should be used when checking array element values against $value

Returns ​

array – The filtered array

filterEmptyStringsFromArray() ​

Filters empty strings from an array.

View source

Arguments ​

Returns ​

array

firstKey() ​

Returns the first key in a given array.

View source

Arguments ​

Returns ​

string, integer, null – 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

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

Arguments ​

  • $array (array, Traversable) – The array that the value will be searched for in
  • $key (string, Closure) – The column name or anonymous function which must be set to $value
  • $value (mixed) – The value that $key should be compared with
  • $strict (boolean) – 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

isNumeric() ​

Since
3.5.0

Returns whether all the elements in the array are numeric.

View source

Arguments ​

Returns ​

boolean

isOrdered() ​

Since
3.4.0

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

View source

Arguments ​

Returns ​

boolean

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

Arguments ​

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

Returns ​

boolean – Whether the value exists in the array

prepend() ​

Since
3.4.0

Prepends values to an array.

This should be used instead of array_unshift($array, ...$values) when $values could be an empty array, as PHP < 7.3 would throw an error in that case.

View source

Arguments ​

  • $array (array) – The array to be prepended to
  • $values (mixed) – The values to prepend.

Example ​

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

prependOrAppend() ​

Prepends or appends a value to an array.

View source

Arguments ​

  • $array (array) – The array to be prepended/appended to
  • $value (mixed) – The value to prepend/append to the array
  • $prepend (boolean) – true will prepend the value; false will append it

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

Arguments ​

  • $array (array) – The array to extract value from
  • $oldKey (string) – Old key name of the array element
  • $newKey (string) – New key name of the array element
  • $default (mixed) – The default value to be set if the specified old key does not exist

toArray() ​

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

View source

Arguments ​

  • $object (object, array, string) – The object to be converted into an array
  • $properties (array) – A mapping from object class names to the properties that need to put into the resulting arrays. The properties specified for each class is an array of the following format:
php
[
    '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:

php
[
    'id' => 123,
    'title' => 'test',
    'createTime' => '2013-01-01 12:00AM',
    'length' => 301,
]
  • $recursive (boolean) – Whether to recursively converts properties which are objects into arrays.

Returns ​

array – 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

Arguments ​

  • $array (array, Traversable) – The array that needs to be indexed or grouped
  • $key (string, Closure) – 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) – Whether a strict type comparison should be used when checking array element values against $value
  • $keepKeys (boolean) – Whether to maintain the array keys. If false, the resulting array will be re-indexed with integers.

Returns ​

array – 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

Arguments ​

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

Returns ​

array – 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,

php
// 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

Arguments ​

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

Returns ​

array – The filtered array

without() ​

Since
3.0.9

Returns a copy of an array without a given key.

View source

Arguments ​

Returns ​

array

withoutValue() ​

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

View source

Arguments ​

  • $array (array)
  • $value (mixed)

Returns ​

array