ArrayUtility

Class with helper functions for array handling

Table of Contents

Methods

arrayDiffAssocRecursive()  : array<string|int, mixed>
Filters values off from first array that also exist in second array. Comparison is done by keys.
arrayDiffKeyRecursive()  : 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.
assertAllArrayKeysAreValid()  : mixed
Validates the given $arrayToTest by checking if an element is not in $allowedArrayKeys.
convertBooleanStringsToBooleanRecursive()  : array<string|int, mixed>
Recursively convert 'true' and 'false' strings to boolean values.
filterAndSortByNumericKeys()  : array<string|int, mixed>
Takes a TypoScript array as input and returns an array which contains all integer properties found which had a value (not only properties). The output array will be sorted numerically.
filterByValueRecursive()  : array<string|int, mixed>
Reduce an array by a search value and keep the array structure.
filterRecursive()  : array<string|int, mixed>
Recursively filter an array
flatten()  : array<string|int, mixed>
Converts a multidimensional array to a flat representation.
flattenPlain()  : array<string|int, mixed>
Just like flatten, but not tailored for TypoScript but for plain simple arrays It is internal for now, as it needs to be decided how to deprecate/ rename flatten
getValueByPath()  : mixed
Returns a value by given path
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.
isAssociative()  : bool
Check whether the array has non-integer keys. If there is at least one string key, $array will be regarded as an associative array.
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()  : mixed
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)
reIndexNumericArrayKeysRecursive()  : array<string|int, mixed>
Reindex keys from the current nesting level if all keys within the current nesting level are integers.
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
removeNullValuesRecursive()  : array<string|int, mixed>
Recursively remove keys if their value are NULL.
renumberKeysToAvoidLeapsIfKeysAreAllNumeric()  : array<string|int, mixed>
Renumber the keys of an array to avoid leaps if keys are all numeric.
replaceAndAppendScalarValuesRecursive()  : array<string|int, mixed>
Same as array_replace_recursive except that when in simple arrays (= YAML lists), the entries are appended (array_merge). The second array takes precedence in case of equal sub arrays.
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
sortArrayWithIntegerKeys()  : array<string|int, mixed>
If the array contains numerical keys only, sort it in ascending order
sortArrayWithIntegerKeysRecursive()  : array<string|int, mixed>
Sort keys from the current nesting level if all keys within the current nesting level are integers.
sortByKeyRecursive()  : array<string|int, mixed>
Sorts an array recursively by key
stripTagsFromValuesRecursive()  : array<string|int, mixed>
Recursively translate values.

Methods

arrayDiffAssocRecursive()

Filters values 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[, bool $useArrayDiffAssocBehavior = false ]) : 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

$useArrayDiffAssocBehavior : bool = false

If false, the old array_diff_key() behavior is kept and a deprecation warning is triggered. Will be removed in TYPO3 v12.

Return values
array<string|int, mixed> —

Source array reduced by values also present in second array, indexed by key

arrayDiffKeyRecursive()

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

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

This method is a recursive version of php array_diff_key()

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 = 0 ]) : 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 = 0

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

Tags
throws
RuntimeException
Return values
string —

String representation of array

assertAllArrayKeysAreValid()

Validates the given $arrayToTest by checking if an element is not in $allowedArrayKeys.

public static assertAllArrayKeysAreValid(array<string|int, mixed> $arrayToTest, array<string|int, mixed> $allowedArrayKeys) : mixed
Parameters
$arrayToTest : array<string|int, mixed>
$allowedArrayKeys : array<string|int, mixed>
Internal
Tags
throws
InvalidArgumentException

if an element in $arrayToTest is not in $allowedArrayKeys

convertBooleanStringsToBooleanRecursive()

Recursively convert 'true' and 'false' strings to boolean values.

public static convertBooleanStringsToBooleanRecursive(array<string|int, mixed> $array) : array<string|int, mixed>
Parameters
$array : array<string|int, mixed>
Return values
array<string|int, mixed> —

the modified array

filterAndSortByNumericKeys()

Takes a TypoScript array as input and returns an array which contains all integer properties found which had a value (not only properties). The output array will be sorted numerically.

public static filterAndSortByNumericKeys(array<string|int, mixed> $setupArr[, bool $acceptAnyKeys = false ]) : array<string|int, mixed>
Parameters
$setupArr : array<string|int, mixed>

TypoScript array with numerical array in

$acceptAnyKeys : bool = false

If set, then a value is not required - the properties alone will be enough.

Tags
see
ContentObjectRenderer::cObjGet()
see
GifBuilder
Return values
array<string|int, mixed> —

An array with all integer properties listed in numeric order.

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

filterRecursive()

Recursively filter an array

public static filterRecursive(array<string|int, mixed> $array[, callable|null $callback = null ][, 0|ARRAY_FILTER_USE_KEY|ARRAY_FILTER_USE_BOTH $mode = 0 ]) : array<string|int, mixed>

Example: filterRecursive( ['a' => ['b' => null]], static fn ($item) => $item !== null, ARRAY_FILTER_USE_BOTH )

Parameters
$array : array<string|int, mixed>
$callback : callable|null = null
$mode : 0|ARRAY_FILTER_USE_KEY|ARRAY_FILTER_USE_BOTH = 0
Tags
see
https://www.php.net/manual/en/function.array-filter.php
Return values
array<string|int, mixed>

flatten()

Converts a multidimensional array to a flat representation.

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

The (relative) array to be converted

$prefix : string = ''

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

$keepDots : bool = false
Tags
todo:

The current implementation isn't a generic array flatten method, but tailored for TypoScript flattening

todo:

It should be deprecated and removed and the required specialities should be put under the domain of TypoScript parsing

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

flattenPlain()

Just like flatten, but not tailored for TypoScript but for plain simple arrays It is internal for now, as it needs to be decided how to deprecate/ rename flatten

public static flattenPlain(array<string|int, mixed> $array) : array<string|int, mixed>
Parameters
$array : array<string|int, mixed>
Internal
Return values
array<string|int, mixed>

getValueByPath()

Returns a value by given path

public static getValueByPath(array<string|int, mixed> $array, array<string|int, mixed>|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 : array<string|int, mixed>|string

Path within the array

$delimiter : string = '/'

Defined path delimiter, default /

Tags
throws
RuntimeException

if the path is empty, or if the path does not exist

throws
InvalidArgumentException

if the path is neither array nor string

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

isAssociative()

Check whether the array has non-integer keys. If there is at least one string key, $array will be regarded as an associative array.

public static isAssociative(array<string|int, mixed> $array) : bool
Parameters
$array : array<string|int, mixed>
Internal
Return values
bool —

True in case a string key was found.

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[, callable|null $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 : callable|null = 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 ]) : mixed

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.

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

reIndexNumericArrayKeysRecursive()

Reindex keys from the current nesting level if all keys within the current nesting level are integers.

public static reIndexNumericArrayKeysRecursive(array<string|int, mixed> $array) : array<string|int, mixed>
Parameters
$array : array<string|int, mixed>
Return values
array<string|int, mixed>

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)

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

removeNullValuesRecursive()

Recursively remove keys if their value are NULL.

public static removeNullValuesRecursive(array<string|int, mixed> $array) : array<string|int, mixed>
Parameters
$array : array<string|int, mixed>
Return values
array<string|int, mixed> —

the 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 = 0 ]) : 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 = 0

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

Return values
array<string|int, mixed>

replaceAndAppendScalarValuesRecursive()

Same as array_replace_recursive except that when in simple arrays (= YAML lists), the entries are appended (array_merge). The second array takes precedence in case of equal sub arrays.

public static replaceAndAppendScalarValuesRecursive(array<string|int, mixed> $array1, array<string|int, mixed> $array2) : array<string|int, mixed>
Parameters
$array1 : array<string|int, mixed>
$array2 : array<string|int, mixed>
Internal
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|array<string|int, mixed>|ArrayAccess $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|array<string|int, mixed>|ArrayAccess

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

sortArrayWithIntegerKeys()

If the array contains numerical keys only, sort it in ascending order

public static sortArrayWithIntegerKeys(array<string|int, mixed> $array) : array<string|int, mixed>
Parameters
$array : array<string|int, mixed>
Return values
array<string|int, mixed>

sortArrayWithIntegerKeysRecursive()

Sort keys from the current nesting level if all keys within the current nesting level are integers.

public static sortArrayWithIntegerKeysRecursive(array<string|int, mixed> $array) : array<string|int, mixed>
Parameters
$array : array<string|int, mixed>
Return values
array<string|int, mixed>

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

stripTagsFromValuesRecursive()

Recursively translate values.

public static stripTagsFromValuesRecursive(array<string|int, mixed> $array) : array<string|int, mixed>
Parameters
$array : array<string|int, mixed>
Return values
array<string|int, mixed> —

the modified array


        

        
    




    

    

                            

            

                            
    

        On this page

        
    


            

                    

        

    

        

            
Search results