HumHub Documentation (unofficial)

BaseArrayHelper
in package

BaseArrayHelper provides concrete implementation for [[ArrayHelper]].

Do not use BaseArrayHelper. Use [[ArrayHelper]] instead.

Tags
author

Qiang Xue qiang.xue@gmail.com

since
2.0

Table of Contents

Methods

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

Methods

filter()

Filters array according to rules specified.

public static filter(array<string|int, mixed> $array, iterable<string|int, mixed> $filters) : array<string|int, mixed>

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],
// ]
Parameters
$array : array<string|int, mixed>

Source array

$filters : iterable<string|int, mixed>

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.
Tags
since
2.0.9
Return values
array<string|int, mixed> —

Filtered array

getColumn()

Returns the values of a specified column in an array.

public static getColumn(array<string|int, mixed> $array, int|string|array<string|int, mixed>|Closure $name[, bool $keepKeys = true ]) : array<string|int, mixed>

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'];
});
Parameters
$array : array<string|int, mixed>
$name : int|string|array<string|int, mixed>|Closure
$keepKeys : bool = true

whether to maintain the array keys. If false, the resulting array will be re-indexed with integers.

Return values
array<string|int, mixed> —

the list of column values

getValue()

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

public static getValue(array<string|int, mixed>|object $array, string|Closure|array<string|int, mixed> $key[, mixed $default = null ]) : mixed

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']);
Parameters
$array : array<string|int, mixed>|object

array or object to extract value from

$key : string|Closure|array<string|int, mixed>

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 = null

the default value to be returned if the specified array key does not exist. Not used when getting value from an object.

Return values
mixed —

the value of the element if found, default value otherwise

htmlDecode()

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

public static htmlDecode(array<string|int, mixed> $data[, bool $valuesOnly = true ]) : array<string|int, mixed>

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.

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

data to be decoded

$valuesOnly : bool = true

whether to decode array values only. If false, then both the array keys and array values will be decoded.

Tags
see
https://www.php.net/manual/en/function.htmlspecialchars-decode.php
Return values
array<string|int, mixed> —

the decoded data

htmlEncode()

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

public static htmlEncode(array<string|int, mixed> $data[, bool $valuesOnly = true ][, string|null $charset = null ]) : array<string|int, mixed>

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.

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

data to be encoded

$valuesOnly : bool = true

whether to encode array values only. If false, both the array keys and array values will be encoded.

$charset : string|null = null

the charset that the data is using. If not set, [[\yii\base\Application::charset]] will be used.

Tags
see
https://www.php.net/manual/en/function.htmlspecialchars.php
Return values
array<string|int, mixed> —

the encoded data

index()

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

public static index(array<string|int, mixed> $array, string|Closure|null $key[, string|array<string|int, string>|array<string|int, Closure>|null $groups = [] ]) : array<string|int, mixed>

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']
        ]
    ]
]
Parameters
$array : array<string|int, mixed>

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|array<string|int, string>|array<string|int, 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 values
array<string|int, mixed> —

the indexed and/or grouped array

isAssociative()

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

public static isAssociative(array<string|int, mixed> $array[, bool $allStrings = true ]) : bool

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.

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

the array being checked

$allStrings : bool = true

whether the array keys must be all strings in order for the array to be treated as associative.

Return values
bool —

whether the array is associative

isIn()

Check whether an array or [[Traversable]] contains an element.

public static isIn(mixed $needle, iterable<string|int, mixed> $haystack[, bool $strict = false ]) : bool

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

Parameters
$needle : mixed

The value to look for.

$haystack : iterable<string|int, mixed>

The set of values to search.

$strict : bool = false

Whether to enable strict (===) comparison.

Tags
throws
InvalidArgumentException

if $haystack is neither traversable nor an array.

see
https://www.php.net/manual/en/function.in-array.php
since
2.0.7
Return values
bool —

true if $needle was found in $haystack, false otherwise.

isIndexed()

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

public static isIndexed(array<string|int, mixed> $array[, bool $consecutive = false ]) : bool

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.

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

the array being checked

$consecutive : bool = false

whether the array keys must be a consecutive sequence in order for the array to be treated as indexed.

Return values
bool —

whether the array is indexed

isSubset()

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

public static isSubset(iterable<string|int, mixed> $needles, iterable<string|int, mixed> $haystack[, bool $strict = false ]) : bool

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.

Parameters
$needles : iterable<string|int, mixed>

The values that must all be in $haystack.

$haystack : iterable<string|int, mixed>

The set of value to search.

$strict : bool = false

Whether to enable strict (===) comparison.

Tags
throws
InvalidArgumentException

if $haystack or $needles is neither traversable nor an array.

since
2.0.7
Return values
bool —

true if $needles is a subset of $haystack, false otherwise.

isTraversable()

Checks whether a variable is an array or [[Traversable]].

public static isTraversable(mixed $var) : bool

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

Parameters
$var : mixed

The variable being evaluated.

Tags
see
https://www.php.net/manual/en/function.is-array.php
since
2.0.8
Return values
bool —

whether $var can be traversed via foreach

keyExists()

Checks if the given array contains the specified key.

public static keyExists(string|int $key, array<string|int, mixed>|ArrayAccess $array[, bool $caseSensitive = true ]) : bool

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

Parameters
$key : string|int

the key to check

$array : array<string|int, mixed>|ArrayAccess

the array with keys to check

$caseSensitive : bool = true

whether the key comparison should be case-sensitive

Return values
bool —

whether the array contains the specified key

map()

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

public static map(array<string|int, mixed> $array, string|Closure $from, string|Closure $to[, string|Closure|null $group = null ]) : array<string|int, mixed>

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',
//     ],
// ]
Parameters
$array : array<string|int, mixed>
$from : string|Closure
$to : string|Closure
$group : string|Closure|null = null
Return values
array<string|int, mixed>

merge()

Merges two or more arrays into one recursively.

public static merge(array<string|int, mixed> $a, array<string|int, mixed> $b) : array<string|int, mixed>

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 [[UnsetArrayValue]] object to unset value from previous array or [[ReplaceArrayValue]] to force replace former value instead of recursive merging.

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

array to be merged to

$b : array<string|int, mixed>

array to be merged from. You can specify additional arrays via third argument, fourth argument etc.

Return values
array<string|int, mixed> —

the merged array (the original arrays are not changed.)

multisort()

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

public static multisort(array<string|int, mixed> &$array, string|Closure|array<string|int, mixed> $key[, int|array<string|int, mixed> $direction = SORT_ASC ][, int|array<string|int, mixed> $sortFlag = SORT_REGULAR ]) : mixed
Parameters
$array : array<string|int, mixed>

the array to be sorted. The array will be modified after calling this method.

$key : string|Closure|array<string|int, mixed>

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 : int|array<string|int, mixed> = SORT_ASC

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 : int|array<string|int, mixed> = SORT_REGULAR

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.

Tags
throws
InvalidArgumentException

if the $direction or $sortFlag parameters do not have correct number of elements as that of $key.

recursiveSort()

Sorts array recursively.

public static recursiveSort(array<string|int, mixed> &$array[, callable|null $sorter = null ]) : array<string|int, mixed>
Parameters
$array : array<string|int, mixed>

An array passing by reference.

$sorter : callable|null = null

The array sorter. If omitted, sort index array by values, sort assoc array by keys.

Return values
array<string|int, mixed>

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.

public static remove(array<string|int, mixed> &$array, string $key[, mixed $default = null ]) : mixed|null

Usage examples,

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

the array to extract value from

$key : string

key name of the array element

$default : mixed = null

the default value to be returned if the specified key does not exist

Return values
mixed|null —

the value of the element if found, default value otherwise

removeValue()

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

public static removeValue(array<string|int, mixed> &$array, mixed $value) : array<string|int, mixed>

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'];
Parameters
$array : array<string|int, mixed>

the array where to look the value from

$value : mixed

the value to remove from the array

Tags
since
2.0.11
Return values
array<string|int, mixed> —

the items that were removed from the array

setValue()

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

public static setValue(array<string|int, mixed> &$array, string|array<string|int, mixed>|null $path, mixed $value) : mixed

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'
         ]
     ]
 ]
Parameters
$array : array<string|int, mixed>

the array to write the value to

$path : string|array<string|int, mixed>|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

Tags
since
2.0.13

toArray()

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

public static toArray(object|array<string|int, mixed>|string $object[, array<string|int, mixed> $properties = [] ][, bool $recursive = true ]) : array<string|int, mixed>
Parameters
$object : object|array<string|int, mixed>|string

the object to be converted into an array

$properties : array<string|int, mixed> = []

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 : bool = true

whether to recursively converts properties which are objects into arrays.

Return values
array<string|int, mixed> —

the array representation of the object


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results