Documentation

ArrayUtil
in package

Class with helper functions for array handling.

Table of Contents

arrayDiffAssocRecursive()  : array<string|int, mixed>
Filters keys off from first array that also exist in second array. Comparison is done by keys.
arrayExport()  : string
Exports an array as string.
filterByValueRecursive()  : array<string|int, mixed>
Reduce an array by a search value and keep the array structure.
flatten()  : array<string|int, mixed>
Converts a multidimensional array to a flat representation.
getValueByPath()  : mixed
Returns a value by given path.
inArray()  : bool
Check if an string item exists in an array.
intersectRecursive()  : array<string|int, mixed>
Determine the intersections between two arrays, recursively comparing keys A complete sub array of $source will be preserved, if the key exists in $mask.
isValidPath()  : bool
Checks if a given path exists in array.
keepItemsInArray()  : array<string|int, mixed>
Filters an array to reduce its elements to match the condition.
mergeRecursiveWithOverrule()  : void
Merges two arrays recursively and "binary safe" (integer keys are overridden as well), overruling similar values in the original array with the values of the overrule array.
naturalKeySortRecursive()  : bool
Sorts an array by key recursive - uses natural sort order (aAbB-zZ).
remapArrayKeys()  : mixed
Rename Array keys with a given mapping table.
removeArrayEntryByValue()  : array<string|int, mixed>
Removes the value $cmpValue from the $array if found there. Returns the modified array.
removeByPath()  : array<string|int, mixed>
Remove a sub part from an array specified by path.
renumberKeysToAvoidLeapsIfKeysAreAllNumeric()  : array<string|int, mixed>
Renumber the keys of an array to avoid leaps if keys are all numeric.
setValueByPath()  : array<string|int, mixed>
Modifies or sets a new value in an array by given path.
sortArraysByKey()  : array<string|int, mixed>
Sort an array of arrays by a given key using uasort.
sortByKeyRecursive()  : array<string|int, mixed>
Sorts an array recursively by key.

Methods

arrayDiffAssocRecursive()

Filters keys off from first array that also exist in second array. Comparison is done by keys.

public static arrayDiffAssocRecursive(array<string|int, mixed> $array1, array<string|int, mixed> $array2) : array<string|int, mixed>

This method is a recursive version of php array_diff_assoc().

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

Source array

$array2 : array<string|int, mixed>

Reduce source array by this array

Return values
array<string|int, mixed> —

Source array reduced by keys also present in second array

arrayExport()

Exports an array as string.

public static arrayExport([array<string|int, mixed> $array = [] ], int $level) : string

Similar to var_export(), but representation follows the PSR-2 and TYPO3 core CGL.

See unit tests for detailed examples

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

Array to export

$level : int

Internal level used for recursion, do not set from outside!

Tags
throws
RuntimeException
Return values
string —

String representation of array

filterByValueRecursive()

Reduce an array by a search value and keep the array structure.

public static filterByValueRecursive([mixed $needle = '' ][, array<string|int, mixed> $haystack = [] ]) : array<string|int, mixed>

Comparison is type strict:

  • For a given needle of type string, integer, array or boolean, value and value type must match to occur in result array
  • For a given object, an object within the array must be a reference to the same object to match (not just different instance of same class)

Example:

  • Needle: 'findMe'
  • Given array: array( 'foo' => 'noMatch', 'bar' => 'findMe', 'foobar => array( 'foo' => 'findMe', ), );
  • Result: array( 'bar' => 'findMe', 'foobar' => array( 'foo' => findMe', ), );

See the unit tests for more examples and expected behaviour

Parameters
$needle : mixed = ''

The value to search for

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

The array in which to search

Return values
array<string|int, mixed> —

$haystack array reduced matching $needle values

flatten()

Converts a multidimensional array to a flat representation.

public static flatten(array<string|int, mixed> $array[, string $prefix = '' ]) : array<string|int, mixed>

See unit tests for more details

Example:

  • array: array( 'first.' => array( 'second' => 1 ) )
  • result: array( 'first.second' => 1 )

Example:

  • array: array( 'first' => array( 'second' => 1 ) )
  • result: array( 'first.second' => 1 )
Parameters
$array : array<string|int, mixed>

The (relative) array to be converted

$prefix : string = ''

The (relative) prefix to be used (e.g. 'section.')

Return values
array<string|int, mixed> —

getValueByPath()

Returns a value by given path.

public static getValueByPath(array<string|int, mixed> $array, string $path[, string $delimiter = '/' ]) : mixed

Example

  • array: array( 'foo' => array( 'bar' => array( 'baz' => 42 ) ) );
  • path: foo/bar/baz
  • return: 42

If a path segments contains a delimiter character, the path segment must be enclosed by " (double quote), see unit tests for details

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

Input array

$path : string

Path within the array

$delimiter : string = '/'

Defined path delimiter, default /

Tags
throws
RuntimeException
Return values
mixed —

inArray()

Check if an string item exists in an array.

public static inArray(array<string|int, mixed> $in_array, string $item) : bool

Please note that the order of function parameters is reverse compared to the PHP function in_array()!!!

Comparison to PHP in_array(): -> $array = array(0, 1, 2, 3); -> variant_a := \TYPO3\CMS\Core\Utility\ArrayUtility::inArray($array, $needle) -> variant_b := in_array($needle, $array) -> variant_c := in_array($needle, $array, TRUE) +---------+-----------+-----------+-----------+ | $needle | variant_a | variant_b | variant_c | +---------+-----------+-----------+-----------+ | '1a' | FALSE | TRUE | FALSE | | '' | FALSE | TRUE | FALSE | | '0' | TRUE | TRUE | FALSE | | 0 | TRUE | TRUE | TRUE | +---------+-----------+-----------+-----------+

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

One-dimensional array of items

$item : string

Item to check for

Return values
bool —

TRUE if $item is in the one-dimensional array $in_array

intersectRecursive()

Determine the intersections between two arrays, recursively comparing keys A complete sub array of $source will be preserved, if the key exists in $mask.

public static intersectRecursive(array<string|int, mixed> $source[, array<string|int, mixed> $mask = [] ]) : array<string|int, mixed>

See unit tests for more examples and edge cases.

Example:

  • source: array( 'key1' => 'bar', 'key2' => array( 'subkey1' => 'sub1', 'subkey2' => 'sub2', ), 'key3' => 'baz', )
  • mask: array( 'key1' => NULL, 'key2' => array( 'subkey1' => exists', ), )
  • return: array( 'key1' => 'bar', 'key2' => array( 'subkey1' => 'sub1', ), )
Parameters
$source : array<string|int, mixed>

Source array

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

Array that has the keys which should be kept in the source array

Return values
array<string|int, mixed> —

Keys which are present in both arrays with values of the source array

isValidPath()

Checks if a given path exists in array.

public static isValidPath(array<string|int, mixed> $array, string $path[, string $delimiter = '/' ]) : bool

Example:

  • array: array( 'foo' => array( 'bar' = 'test', ) );
  • path: 'foo/bar'
  • return: TRUE
Parameters
$array : array<string|int, mixed>

Given array

$path : string

Path to test, 'foo/bar/foobar'

$delimiter : string = '/'

Delimiter for path, default /

Return values
bool —

TRUE if path exists in array

keepItemsInArray()

Filters an array to reduce its elements to match the condition.

public static keepItemsInArray(array<string|int, mixed> $array, mixed $keepItems[, string $getValueFunc = null ]) : array<string|int, mixed>

The values in $keepItems can be optionally evaluated by a custom callback function.

Example (arguments used to call this function): $array = array( array('aa' => array('first', 'second'), array('bb' => array('third', 'fourth'), array('cc' => array('fifth', 'sixth'), ); $keepItems = array('third'); $getValueFunc = function($value) { return $value[0]; }

Returns: array( array('bb' => array('third', 'fourth'), )

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

The initial array to be filtered/reduced

$keepItems : mixed

The items which are allowed/kept in the array - accepts array or csv string

$getValueFunc : string = null

(optional) Callback function used to get the value to keep

Return values
array<string|int, mixed> —

The filtered/reduced array with the kept items

mergeRecursiveWithOverrule()

Merges two arrays recursively and "binary safe" (integer keys are overridden as well), overruling similar values in the original array with the values of the overrule array.

public static mergeRecursiveWithOverrule(array<string|int, mixed> &$original, array<string|int, mixed> $overrule[, bool $addKeys = true ][, bool $includeEmptyValues = true ][, bool $enableUnsetFeature = true ]) : void

In case of identical keys, ie. keeping the values of the overrule array.

This method takes the original array by reference for speed optimization with large arrays

The differences to the existing PHP function array_merge_recursive() are:

  • Keys of the original array can be unset via the overrule array. ($enableUnsetFeature)
  • Much more control over what is actually merged. ($addKeys, $includeEmptyValues)
  • Elements or the original array get overwritten if the same key is present in the overrule array.
Parameters
$original : array<string|int, mixed>

Original array. It will be modified by this method and contains the result afterwards!

$overrule : array<string|int, mixed>

Overrule array, overruling the original array

$addKeys : bool = true

If set to FALSE, keys that are NOT found in $original will not be set. Thus only existing value can/will be overruled from overrule array.

$includeEmptyValues : bool = true

If set, values from $overrule will overrule if they are empty or zero.

$enableUnsetFeature : bool = true

If set, special values "__UNSET" can be used in the overrule array in order to unset array keys in the original array.

Return values
void —

naturalKeySortRecursive()

Sorts an array by key recursive - uses natural sort order (aAbB-zZ).

public static naturalKeySortRecursive(array<string|int, mixed> &$array) : bool
Parameters
$array : array<string|int, mixed>

array to be sorted recursively, passed by reference

Return values
bool —

always TRUE

remapArrayKeys()

Rename Array keys with a given mapping table.

public static remapArrayKeys(array<string|int, mixed> &$array, array<string|int, mixed> $mappingTable) : mixed
Parameters
$array : array<string|int, mixed>

Array by reference which should be remapped

$mappingTable : array<string|int, mixed>

Array with remap information, array/$oldKey => $newKey)

Return values
mixed —

removeArrayEntryByValue()

Removes the value $cmpValue from the $array if found there. Returns the modified array.

public static removeArrayEntryByValue(array<string|int, mixed> $array, string $cmpValue) : array<string|int, mixed>
Parameters
$array : array<string|int, mixed>

Array containing the values

$cmpValue : string

Value to search for and if found remove array entry where found.

Return values
array<string|int, mixed> —

Output array with entries removed if search string is found

removeByPath()

Remove a sub part from an array specified by path.

public static removeByPath(array<string|int, mixed> $array, string $path[, string $delimiter = '/' ]) : array<string|int, mixed>
Parameters
$array : array<string|int, mixed>

Input array to manipulate

$path : string

Path to remove from array

$delimiter : string = '/'

Path delimiter

Tags
throws
RuntimeException
Return values
array<string|int, mixed> —

Modified array

renumberKeysToAvoidLeapsIfKeysAreAllNumeric()

Renumber the keys of an array to avoid leaps if keys are all numeric.

public static renumberKeysToAvoidLeapsIfKeysAreAllNumeric([array<string|int, mixed> $array = [] ], int $level) : array<string|int, mixed>

Is called recursively for nested arrays.

Example:

Given array(0 => 'Zero' 1 => 'One', 2 => 'Two', 4 => 'Three') as input, it will return array(0 => 'Zero' 1 => 'One', 2 => 'Two', 3 => 'Three')

Will treat keys string representations of number (ie. '1') equal to the numeric value (ie. 1).

Example: Given array('0' => 'Zero', '1' => 'One' ) it will return array(0 => 'Zero', 1 => 'One')

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

Input array

$level : int

Internal level used for recursion, do not set from outside!

Return values
array<string|int, mixed> —

setValueByPath()

Modifies or sets a new value in an array by given path.

public static setValueByPath(array<string|int, mixed> $array, string $path, mixed $value[, string $delimiter = '/' ]) : array<string|int, mixed>

Example:

  • array: array( 'foo' => array( 'bar' => 42, ), );
  • path: foo/bar
  • value: 23
  • return: array( 'foo' => array( 'bar' => 23, ), );
Parameters
$array : array<string|int, mixed>

Input array to manipulate

$path : string

Path in array to search for

$value : mixed

Value to set at path location in array

$delimiter : string = '/'

Path delimiter

Tags
throws
RuntimeException
Return values
array<string|int, mixed> —

Modified array

sortArraysByKey()

Sort an array of arrays by a given key using uasort.

public static sortArraysByKey(array<string|int, mixed> $arrays, string $key[, bool $ascending = true ]) : array<string|int, mixed>
Parameters
$arrays : array<string|int, mixed>

Array of arrays to sort

$key : string

Key to sort after

$ascending : bool = true

Set to TRUE for ascending order, FALSE for descending order

Tags
throws
RuntimeException
Return values
array<string|int, mixed> —

Array of sorted arrays

sortByKeyRecursive()

Sorts an array recursively by key.

public static sortByKeyRecursive(array<string|int, mixed> $array) : array<string|int, mixed>
Parameters
$array : array<string|int, mixed>

Array to sort recursively by key

Return values
array<string|int, mixed> —

Sorted array

Search results