# Class yii\helpers\BaseArrayHelper

Inheritance | yii\helpers\BaseArrayHelper
Subclasses | yii\helpers\ArrayHelper
Available since version | 2.0
Source Code | https://github.com/yiisoft/yii2/blob/master/framework/helpers/BaseArrayHelper.php

BaseArrayHelper provides concrete implementation for yii\helpers\ArrayHelper.

Do not use BaseArrayHelper. Use yii\helpers\ArrayHelper instead.

## Public Methods

Hide inherited methods

Method | Description | Defined By
--- | --- | ---
filter() | Filters array according to rules specified. | yii\helpers\BaseArrayHelper
getColumn() | Returns the values of a specified column in an array. | yii\helpers\BaseArrayHelper
getValue() | Retrieves the value of an array element or object property with the given key or property name. | yii\helpers\BaseArrayHelper
htmlDecode() | Decodes HTML entities into the corresponding characters in an array of strings. | yii\helpers\BaseArrayHelper
htmlEncode() | Encodes special characters in an array of strings into HTML entities. | yii\helpers\BaseArrayHelper
index() | Indexes and/or groups the array according to a specified key. | yii\helpers\BaseArrayHelper
isAssociative() | Returns a value indicating whether the given array is an associative array. | yii\helpers\BaseArrayHelper
isIn() | Check whether an array or Traversable contains an element. | yii\helpers\BaseArrayHelper
isIndexed() | Returns a value indicating whether the given array is an indexed array. | yii\helpers\BaseArrayHelper
isSubset() | Checks whether an array or Traversable is a subset of another array or Traversable. | yii\helpers\BaseArrayHelper
isTraversable() | Checks whether a variable is an array or Traversable. | yii\helpers\BaseArrayHelper
keyExists() | Checks if the given array contains the specified key. | yii\helpers\BaseArrayHelper
map() | Builds a map (key-value pairs) from a multidimensional array or an array of objects. | yii\helpers\BaseArrayHelper
merge() | Merges two or more arrays into one recursively. | yii\helpers\BaseArrayHelper
multisort() | Sorts an array of objects or arrays (with the same structure) by one or several keys. | yii\helpers\BaseArrayHelper
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. | yii\helpers\BaseArrayHelper
removeValue() | Removes items with matching values from the array and returns the removed items. | yii\helpers\BaseArrayHelper
setValue() | Writes a value into an associative array at the key path specified. | yii\helpers\BaseArrayHelper
toArray() | Converts an object or an array of objects into an array. | yii\helpers\BaseArrayHelper

## Method Details

filter() public static method (available since version 2.0.9)

Filters array according to rules specified.

For example:

    $array = [
        'A' => [1, 2],
        'B' => [
            'C' => 1,
            'D' => 2,
        ],
        'E' => 1,
    ];

    $result = \yii\helpers\ArrayHelper::filter($array, ['A']);
    // $result will be:
    // [
    //     'A' => [1, 2],
    // ]

    $result = \yii\helpers\ArrayHelper::filter($array, ['A', 'B.C']);
    // $result will be:
    // [
    //     'A' => [1, 2],
    //     'B' => ['C' => 1],
    // ]

    $result = \yii\helpers\ArrayHelper::filter($array, ['B', '!B.C']);
    // $result will be:
    // [
    //     'B' => ['D' => 2],
    // ]

public static array filter ( $array, $filters )
$array | array | Source array
$filters | array | Rules that define array keys which should be left or removed from results. Each rule is: `var` - `$array['var']` will be left in result. `var.key` = only `$array['var']['key'] will be left in result. `!var.key` = `$array['var']['key'] will be removed from result.
return | array | Filtered array

getColumn() public static method

Returns the values of a specified column in an array.

The input array should be multidimensional or an array of objects.

For example,

    $array = [
        ['id' => '123', 'data' => 'abc'],
        ['id' => '345', 'data' => 'def'],
    ];
    $result = ArrayHelper::getColumn($array, 'id');
    // the result is: ['123', '345']

    // using anonymous function
    $result = ArrayHelper::getColumn($array, function ($element) {
        return $element['id'];
    });

public static array getColumn ( $array, $name, $keepKeys = true )
$array | array |
$name | integer|string|Closure |
$keepKeys | boolean | Whether to maintain the array keys. If false, the resulting array will be re-indexed with integers.
return | array | The list of column values

getValue() public static method

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']);

public static mixed getValue ( $array, $key, $default = null )
$array | array|object | Array or object to extract value from
$key | string|Closure|array | Key name of the array element, an array of keys or property name of the object, or an anonymous function returning the value. The anonymous function signature should be: `function($array, $defaultValue)`. The possibility to pass an array of keys is available since version 2.0.4.
$default | mixed | The default value to be returned if the specified array key does not exist. Not used when getting value from an object.
return | mixed | The value of the element if found, default value otherwise

htmlDecode() public static method

Decodes HTML entities into the corresponding characters in an array of strings.

Only array values will be decoded by default. If a value is an array, this method will also decode it recursively. Only string values will be decoded.

See also https://secure.php.net/manual/en/function.htmlspecialchars-decode.php.

public static array htmlDecode ( $data, $valuesOnly = true )
$data | array | Data to be decoded
$valuesOnly | boolean | Whether to decode array values only. If false, both the array keys and array values will be decoded.
return | array | The decoded data

htmlEncode() public static method

Encodes special characters in an array of strings into HTML entities.

Only array values will be encoded by default. If a value is an array, this method will also encode it recursively. Only string values will be encoded.

See also https://secure.php.net/manual/en/function.htmlspecialchars.php.

public static array htmlEncode ( $data, $valuesOnly = true, $charset = null )
$data | array | Data to be encoded
$valuesOnly | boolean | Whether to encode array values only. If false, both the array keys and array values will be encoded.
$charset | string | The charset that the data is using. If not set, yii\base\Application::$charset will be used.
return | array | The encoded data

index() public static method

Indexes and/or groups the array according to a specified key.

The input should be either multidimensional array or an array of objects.

The $key can be either a key name of the sub-array, a property name of object, or an anonymous function that must return the value that will be used as a key.

$groups is an array of keys, that will be used to group the input array into one or more sub-arrays based on keys specified.

If the `$key` is specified as `null` or a value of an element corresponding to the key is `null` in addition to `$groups` not specified then the element is discarded.

For example:

    $array = [
        ['id' => '123', 'data' => 'abc', 'device' => 'laptop'],
        ['id' => '345', 'data' => 'def', 'device' => 'tablet'],
        ['id' => '345', 'data' => 'hgi', 'device' => 'smartphone'],
    ];
    $result = ArrayHelper::index($array, 'id');

The result will be an associative array, where the key is the value of `id` attribute

    [
        '123' => ['id' => '123', 'data' => 'abc', 'device' => 'laptop'],
        '345' => ['id' => '345', 'data' => 'hgi', 'device' => 'smartphone']
        // The second element of an original array is overwritten by the last element because of the same id
    ]

An anonymous function can be used in the grouping array as well.

    $result = ArrayHelper::index($array, function ($element) {
        return $element['id'];
    });

Passing `id` as a third argument will group `$array` by `id`:

    $result = ArrayHelper::index($array, null, 'id');

The result will be a multidimensional array grouped by `id` on the first level, by `device` on the second level and indexed by `data` on the third level:

    [
        '123' => [
            ['id' => '123', 'data' => 'abc', 'device' => 'laptop']
        ],
        '345' => [ // all elements with this index are present in the result array
            ['id' => '345', 'data' => 'def', 'device' => 'tablet'],
            ['id' => '345', 'data' => 'hgi', 'device' => 'smartphone'],
        ]
    ]

The anonymous function can be used in the array of grouping keys as well:

    $result = ArrayHelper::index($array, 'data', [function ($element) {
        return $element['id'];
    }, 'device']);

The result will be a multidimensional array grouped by `id` on the first level, by the `device` on the second one and indexed by the `data` on the third level:

    [
        '123' => [
            'laptop' => [
                'abc' => ['id' => '123', 'data' => 'abc', 'device' => 'laptop']
            ]
        ],
        '345' => [
            'tablet' => [
                'def' => ['id' => '345', 'data' => 'def', 'device' => 'tablet']
            ],
            'smartphone' => [
                'hgi' => ['id' => '345', 'data' => 'hgi', 'device' => 'smartphone']
            ]
        ]
    ]

public static array index ( $array, $key, $groups = [] )
$array | array | The array that needs to be indexed or grouped
$key | string|Closure|null | The column name or anonymous function which result will be used to index the array
$groups | string|string[]|Closure[]|null | The array of keys, that will be used to group the input array by one or more keys. If the $key attribute or its value for the particular element is null and $groups is not defined, the array element will be discarded. Otherwise, if $groups is specified, array element will be added to the result array without any key. This parameter is available since version 2.0.8.
return | array | The indexed and/or grouped array

isAssociative() public static method

Returns a value indicating whether the given array is an associative array.

An array is associative if all its keys are strings. If `$allStrings` is false, then an array will be treated as associative if at least one of its keys is a string.

Note that an empty array will NOT be considered associative.

public static boolean isAssociative ( $array, $allStrings = true )
$array | array | The array being checked
$allStrings | boolean | Whether the array keys must be all strings in order for the array to be treated as associative.
return | boolean | Whether the array is associative

isIn() public static method (available since version 2.0.7)

Check whether an array or Traversable contains an element.

This method does the same as the PHP function in_array() but additionally works for objects that implement the Traversable interface.

See also https://secure.php.net/manual/en/function.in-array.php.

public static boolean isIn ( $needle, $haystack, $strict = false )
$needle | mixed | The value to look for.
$haystack | array|Traversable | The set of values to search.
$strict | boolean | Whether to enable strict (`===`) comparison.
return | boolean | `true` if `$needle` was found in `$haystack`, `false` otherwise.
throws | yii\base\InvalidArgumentException | if `$haystack` is neither traversable nor an array.

isIndexed() public static method

Returns a value indicating whether the given array is an indexed array.

An array is indexed if all its keys are integers. If `$consecutive` is true, then the array keys must be a consecutive sequence starting from 0.

Note that an empty array will be considered indexed.

public static boolean isIndexed ( $array, $consecutive = false )
$array | array | The array being checked
$consecutive | boolean | Whether the array keys must be a consecutive sequence in order for the array to be treated as indexed.
return | boolean | Whether the array is indexed

isSubset() public static method (available since version 2.0.7)

Checks whether an array or Traversable is a subset of another array or Traversable.

This method will return `true`, if all elements of `$needles` are contained in `$haystack`. If at least one element is missing, `false` will be returned.

public static boolean isSubset ( $needles, $haystack, $strict = false )
$needles | array|Traversable | The values that must all be in `$haystack`.
$haystack | array|Traversable | The set of value to search.
$strict | boolean | Whether to enable strict (`===`) comparison.
return | boolean | `true` if `$needles` is a subset of `$haystack`, `false` otherwise.
throws | yii\base\InvalidArgumentException | if `$haystack` or `$needles` is neither traversable nor an array.

isTraversable() public static method (available since version 2.0.8)

Checks whether a variable is an array or Traversable.

This method does the same as the PHP function is_array() but additionally works on objects that implement the Traversable interface.

See also https://secure.php.net/manual/en/function.is-array.php.

public static boolean isTraversable ( $var )
$var | mixed | The variable being evaluated.
return | boolean | Whether $var can be traversed via foreach

keyExists() public static method

Checks if the given array contains the specified key.

This method enhances the `array_key_exists()` function by supporting case-insensitive key comparison.

public static boolean keyExists ( $key, $array, $caseSensitive = true )
$key | string | The key to check
$array | array|ArrayAccess | The array with keys to check
$caseSensitive | boolean | Whether the key comparison should be case-sensitive
return | boolean | Whether the array contains the specified key

map() public static method

Builds a map (key-value pairs) from a multidimensional array or an array of objects.

The `$from` and `$to` parameters specify the key names or property names to set up the map. Optionally, one can further group the map according to a grouping field `$group`.

For example,

    $array = [
        ['id' => '123', 'name' => 'aaa', 'class' => 'x'],
        ['id' => '124', 'name' => 'bbb', 'class' => 'x'],
        ['id' => '345', 'name' => 'ccc', 'class' => 'y'],
    ];

    $result = ArrayHelper::map($array, 'id', 'name');
    // the result is:
    // [
    //     '123' => 'aaa',
    //     '124' => 'bbb',
    //     '345' => 'ccc',
    // ]

    $result = ArrayHelper::map($array, 'id', 'name', 'class');
    // the result is:
    // [
    //     'x' => [
    //         '123' => 'aaa',
    //         '124' => 'bbb',
    //     ],
    //     'y' => [
    //         '345' => 'ccc',
    //     ],
    // ]

public static array map ( $array, $from, $to, $group = null )
$array | array |
$from | string|Closure |
$to | string|Closure |
$group | string|Closure |

merge() public static method

Merges two or more arrays into one recursively.

If each array has an element with the same string key value, the latter will overwrite the former (different from array_merge_recursive). Recursive merging will be conducted if both arrays have an element of array type and are having the same key. For integer-keyed elements, the elements from the latter array will be appended to the former array. You can use yii\helpers\UnsetArrayValue object to unset value from previous array or yii\helpers\ReplaceArrayValue to force replace former value instead of recursive merging.

public static array merge ( $a, $b )
$a | array | Array to be merged to
$b | array | Array to be merged from. You can specify additional arrays via third argument, fourth argument etc.
return | array | The merged array (the original arrays are not changed.)

multisort() public static method

Sorts an array of objects or arrays (with the same structure) by one or several keys.

public static void multisort ( &$array, $key, $direction = SORT_ASC, $sortFlag = SORT_REGULAR )
$array | array | The array to be sorted. The array will be modified after calling this method.
$key | string|Closure|array | The key(s) to be sorted by. This refers to a key name of the sub-array elements, a property name of the objects, or an anonymous function returning the values for comparison purpose. The anonymous function signature should be: `function($item)`. To sort by multiple keys, provide an array of keys here.
$direction | integer|array | The sorting direction. It can be either `SORT_ASC` or `SORT_DESC`. When sorting by multiple keys with different sorting directions, use an array of sorting directions.
$sortFlag | integer|array | The PHP sort flag. Valid values include `SORT_REGULAR`, `SORT_NUMERIC`, `SORT_STRING`, `SORT_LOCALE_STRING`, `SORT_NATURAL` and `SORT_FLAG_CASE`. Please refer to PHP manual for more details. When sorting by multiple keys with different sort flags, use an array of sort flags.
throws | yii\base\InvalidArgumentException | if the $direction or $sortFlag parameters do not have correct number of elements as that of $key.

remove() public static method

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.

Usage examples,

    // $array = ['type' => 'A', 'options' => [1, 2]];
    // working with array
    $type = \yii\helpers\ArrayHelper::remove($array, 'type');
    // $array content
    // $array = ['options' => [1, 2]];

public static mixed|null remove ( &$array, $key, $default = null )
$array | array | The array to extract value from
$key | string | Key name of the array element
$default | mixed | The default value to be returned if the specified key does not exist
return | mixed|null | The value of the element if found, default value otherwise

removeValue() public static method (available since version 2.0.11)

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'];

public static array removeValue ( &$array, $value )
$array | array | The array where to look the value from
$value | string | The value to remove from the array
return | array | The items that were removed from the array

setValue() public static method (available since version 2.0.13)

Writes a value into an associative array at the key path specified.

If there is no such key path yet, it will be created recursively. If the key exists, it will be overwritten.

     $array = [
         'key' => [
             'in' => [
                 'val1',
                 'key' => 'val'
             ]
         ]
     ];

The result of `ArrayHelper::setValue($array, 'key.in.0', ['arr' => 'val']);` will be the following:

     [
         'key' => [
             'in' => [
                 ['arr' => 'val'],
                 'key' => 'val'
             ]
         ]
     ]

The result of `ArrayHelper::setValue($array, 'key.in', ['arr' => 'val']);` or `ArrayHelper::setValue($array, ['key', 'in'], ['arr' => 'val']);` will be the following:

     [
         'key' => [
             'in' => [
                 'arr' => 'val'
             ]
         ]
     ]

public static void setValue ( &$array, $path, $value )
$array | array | The array to write the value to
$path | string|array|null | The path of where do you want to write a value to `$array` the path can be described by a string when each key should be separated by a dot you can also describe the path as an array of keys if the path is null then `$array` will be assigned the `$value`
$value | mixed | The value to be written

toArray() public static method

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

public static array toArray ( $object, $properties = [], $recursive = true )
$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:
    [
        '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,
    ]
$recursive | boolean | Whether to recursively converts properties which are objects into arrays.
return | array | The array representation of the object