TYPO3\CMS\Core\Utility\ArrayUtility Class Reference

Inheritance diagram for TYPO3\CMS\Core\Utility\ArrayUtility:

Static Public Member Functions
static	filterByValueRecursive ($needle='', array $haystack=array())
static	isValidPath (array $array, $path, $delimiter='/')
static	getValueByPath (array $array, $path, $delimiter='/')
static	setValueByPath (array $array, $path, $value, $delimiter='/')
static	removeByPath (array $array, $path, $delimiter='/')
static	sortByKeyRecursive (array $array)
static	sortArraysByKey (array $arrays, $key, $ascending=TRUE)
static	arrayExport (array $array=array(), $level=0)
static	flatten (array $array, $prefix='')
static	intersectRecursive (array $source, array $mask=array())
static	renumberKeysToAvoidLeapsIfKeysAreAllNumeric (array $array=array(), $level=0)
static	mergeRecursiveWithOverrule (array &$original, array $overrule, $addKeys=TRUE, $includeEmptyValues=TRUE, $enableUnsetFeature=TRUE)

Detailed Description

This file is part of the TYPO3 CMS project.

It is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License, either version 2 of the License, or any later version.

For the full copyright and license information, please read the LICENSE.txt file that was distributed with this source code.

The TYPO3 project - inspiring people to share! Class with helper functions for array handling

Author

Susanne Moog typo3.nosp@m.@sus.nosp@m.anne-.nosp@m.moog.nosp@m..de

Definition at line 21 of file ArrayUtility.php.

Member Function Documentation

arrayExport()

static TYPO3\CMS\Core\Utility\ArrayUtility::arrayExport ( array  $array = array(),   $level = 0  )

static

Exports an array as string. Similar to var_export(), but representation follows the TYPO3 core CGL.

See unit tests for detailed examples

Parameters

array	$array	Array to export
integer	$level	Internal level used for recursion, do not set from outside!

Returns

string String representation of array

Exceptions

Definition at line 302 of file ArrayUtility.php.

Referenced by TYPO3\CMS\Core\Tests\Unit\Utility\ArrayUtilityTest\arrayExportReturnsFormattedMultidimensionalArray(), TYPO3\CMS\Core\Tests\Unit\Utility\ArrayUtilityTest\arrayExportReturnsKeyIndexForNonConsecutiveCountedArrays(), TYPO3\CMS\Core\Tests\Unit\Utility\ArrayUtilityTest\arrayExportReturnsNoKeyIndexForConsecutiveCountedArrays(), TYPO3\CMS\Core\Tests\Unit\Utility\ArrayUtilityTest\arrayExportReturnsNumericArrayKeys(), TYPO3\CMS\Core\Tests\Unit\Utility\ArrayUtilityTest\arrayExportThrowsExceptionIfObjectShouldBeExported(), and TYPO3\CMS\Core\Configuration\ConfigurationManager\writeLocalConfiguration().

filterByValueRecursive()

static TYPO3\CMS\Core\Utility\ArrayUtility::filterByValueRecursive (   $needle = '', array  $haystack = array()  )

static

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

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, a 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

mixed	$needle	The value to search for
array	$haystack	The array in which to search

Returns

array $haystack array reduced matching $needle values

Definition at line 56 of file ArrayUtility.php.

Referenced by TYPO3\CMS\Core\Utility\ExtensionManagementUtility\addTcaSelectItem(), TYPO3\CMS\Core\Tests\Unit\Utility\ArrayUtilityTest\filterByValueRecursiveCorrectlyFiltersArray(), TYPO3\CMS\Core\Tests\Unit\Utility\ArrayUtilityTest\filterByValueRecursiveDoesNotMatchDifferentInstancesOfSameClass(), and TYPO3\CMS\Core\Tests\Unit\Utility\ArrayUtilityTest\filterByValueRecursiveMatchesReferencesToSameObject().

flatten()

static TYPO3\CMS\Core\Utility\ArrayUtility::flatten ( array  $array,   $prefix = ''  )

static

Converts a multidimensional array to a flat representation.

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	The (relative) array to be converted
string	$prefix	The (relative) prefix to be used (e.g. 'section.')

Returns

array

Definition at line 383 of file ArrayUtility.php.

Referenced by TYPO3\CMS\Extensionmanager\Utility\ConfigurationUtility\convertNestedToValuedConfiguration(), TYPO3\CMS\Core\Tests\Unit\Utility\ArrayUtilityTest\flattenCalculatesExpectedResult(), and TYPO3\CMS\Extensionmanager\Domain\Repository\ConfigurationItemRepository\mergeWithExistingConfiguration().

getValueByPath()

static TYPO3\CMS\Core\Utility\ArrayUtility::getValueByPath ( array  $array,   $path,   $delimiter = '/'  )

static

Returns a value by given path

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	Input array
string	$path	Path within the array
string	$delimiter	Defined path delimiter, default /

Returns

mixed

Exceptions

Definition at line 130 of file ArrayUtility.php.

Referenced by TYPO3\CMS\Core\Configuration\ConfigurationManager\getConfigurationValueByPath(), TYPO3\CMS\Core\Configuration\ConfigurationManager\getDefaultConfigurationValueByPath(), TYPO3\CMS\Backend\View\BackendLayoutView\getIdentifiersToBeExcluded(), TYPO3\CMS\Core\Configuration\ConfigurationManager\getLocalConfigurationValueByPath(), TYPO3\CMS\Core\Tests\Unit\Utility\ArrayUtilityTest\getValueByPathAccpetsDifferentDelimeter(), TYPO3\CMS\Core\Tests\Unit\Utility\ArrayUtilityTest\getValueByPathGetsCorrectValue(), TYPO3\CMS\Core\Tests\Unit\Utility\ArrayUtilityTest\getValueByPathThrowsExceptionIfPathIsEmpty(), and TYPO3\CMS\Core\Tests\Unit\Utility\ArrayUtilityTest\getValueByPathThrowsExceptionIfPathNotExists().

intersectRecursive()

static TYPO3\CMS\Core\Utility\ArrayUtility::intersectRecursive ( array  $source, array  $mask = array()  )

static

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

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

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

Returns

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

Definition at line 432 of file ArrayUtility.php.

Referenced by TYPO3\CMS\Felogin\Controller\FrontendLoginController\getPreserveGetVars(), and TYPO3\CMS\Core\Tests\Unit\Utility\ArrayUtilityTest\intersectRecursiveCalculatesExpectedResult().

isValidPath()

static TYPO3\CMS\Core\Utility\ArrayUtility::isValidPath ( array  $array,   $path,   $delimiter = '/'  )

static

Checks if a given path exists in array

Example:

• array: array( 'foo' => array( 'bar' = 'test', ) );
• path: 'foo/bar'
• return: TRUE

Parameters

array	$array	Given array
string	$path	Path to test, 'foo/bar/foobar'
string	$delimiter	Delimeter for path, default /

Returns

boolean TRUE if path exists in array

Definition at line 95 of file ArrayUtility.php.

Referenced by TYPO3\CMS\Backend\View\BackendLayoutView\getIdentifiersToBeExcluded(), TYPO3\CMS\Core\Configuration\ConfigurationManager\isValidLocalConfigurationPath(), and TYPO3\CMS\Core\Configuration\ConfigurationManager\removeLocalConfigurationKeysByPath().

mergeRecursiveWithOverrule()

static TYPO3\CMS\Core\Utility\ArrayUtility::mergeRecursiveWithOverrule ( array &  $original, array  $overrule,   $addKeys = TRUE,   $includeEmptyValues = TRUE,   $enableUnsetFeature = TRUE  )

static

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. 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

array	$original	Original array. It will be modified by this method and contains the result afterwards!
array	$overrule	Overrule array, overruling the original array
boolean	$addKeys	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.
boolean	$includeEmptyValues	If set, values from $overrule will overrule if they are empty or zero.
boolean	$enableUnsetFeature	If set, special values "__UNSET" can be used in the overrule array in order to unset array keys in the original array.

Returns

void

Definition at line 517 of file ArrayUtility.php.

Referenced by TYPO3\CMS\Backend\Form\Element\SuggestDefaultReceiver\__construct(), TYPO3\CMS\Backend\Template\DocumentTemplate\__construct(), TYPO3\CMS\Core\Utility\GeneralUtility\_GETset(), TYPO3\CMS\Core\Utility\GeneralUtility\_GPmerged(), TYPO3\CMS\Core\Utility\ExtensionManagementUtility\addExtJSModule(), TYPO3\CMS\Core\Page\PageRenderer\addRequireJsConfiguration(), TYPO3\CMS\Core\Resource\Collection\FileCollectionRegistry\addTypeToTCA(), TYPO3\CMS\Core\Utility\GeneralUtility\array_merge_recursive_overrule(), TYPO3\CMS\Core\Tests\Unit\Utility\ArrayUtilityTest\arrayMergeRecursiveOverruleDoesConsiderUnsetValues(), TYPO3\CMS\Extbase\Mvc\Web\Routing\UriBuilder\buildBackendUri(), TYPO3\CMS\Extbase\Persistence\Generic\Mapper\DataMapFactory\buildDataMap(), TYPO3\CMS\Core\DataHandling\DataHandler\checkValue_flex(), TYPO3\CMS\Core\DataHandling\DataHandler\checkValue_flex_procInData_travDS(), TYPO3\CMS\Core\Configuration\ConfigurationManager\createLocalConfigurationFromFactoryConfiguration(), TYPO3\CMS\Extensionmanager\Controller\ConfigurationController\emitAfterExtensionConfigurationWriteSignal(), TYPO3\CMS\Core\Configuration\ConfigurationManager\exportConfiguration(), TYPO3\CMS\Core\TypoScript\ConfigurationForm\ext_mergeIncomingWithExisting(), TYPO3\CMS\Extensionmanager\Domain\Repository\ConfigurationItemRepository\findByExtensionKey(), TYPO3\CMS\Core\DataHandling\DataHandler\getCheckModifyAccessListHookObjects(), TYPO3\CMS\Frontend\Controller\TypoScriptFrontendController\getConfigArray(), TYPO3\CMS\Extbase\Configuration\AbstractConfigurationManager\getConfiguration(), TYPO3\CMS\Core\Configuration\ConfigurationManager\getConfigurationValueByPath(), TYPO3\CMS\Extensionmanager\Utility\ConfigurationUtility\getCurrentConfiguration(), TYPO3\CMS\Frontend\ContentObject\ContentObjectRenderer\getData(), TYPO3\CMS\Core\Utility\ExtensionManagementUtility\getFileFieldTCAConfig(), TYPO3\CMS\Backend\Utility\BackendUtility\getModTSconfig(), TYPO3\CMS\Backend\Utility\BackendUtility\getPagesTSconfig(), TYPO3\CMS\Core\Localization\Parser\LocallangXmlParser\getParsedData(), TYPO3\CMS\Core\DataHandling\DataHandler\getPlaceholderTitleForTableLabel(), TYPO3\CMS\Extbase\Configuration\FrontendConfigurationManager\getPluginConfiguration(), TYPO3\CMS\Extbase\Configuration\BackendConfigurationManager\getPluginConfiguration(), TYPO3\CMS\Backend\Form\Element\InlineElement\getPossibleRecordsSelectorConfig(), TYPO3\CMS\Core\Resource\FileReference\getProperties(), TYPO3\CMS\Core\DataHandling\DataHandler\getTableEntries(), TYPO3\CMS\Core\Category\CategoryRegistry\getTcaFieldConfiguration(), TYPO3\CMS\Backend\Utility\BackendUtility\getTCEFORM_TSconfig(), TYPO3\CMS\Backend\Module\AbstractFunctionModule\incLocalLang(), TYPO3\CMS\Lang\LanguageService\includeLLFile(), TYPO3\CMS\Fluid\ViewHelpers\Widget\Controller\PaginateController\initializeAction(), TYPO3\CMS\Fluid\ViewHelpers\Be\Widget\Controller\PaginateController\initializeAction(), TYPO3\CMS\Core\Utility\GeneralUtility\linkThisUrl(), TYPO3\CMS\Form\View\Wizard\WizardView\loadLocalization(), TYPO3\CMS\Linkvalidator\Task\ValidatorTask\loadModTsConfig(), TYPO3\CMS\Core\Localization\LocalizationFactory\localizationOverride(), TYPO3\CMS\Rtehtmlarea\RteHtmlAreaApi\main(), TYPO3\CMS\Lowlevel\View\ConfigurationView\main(), TYPO3\CMS\Rtehtmlarea\User\main_user(), TYPO3\CMS\Extbase\Configuration\FrontendConfigurationManager\mergeConfigurationIntoFrameworkConfiguration(), TYPO3\CMS\Version\DataHandler\CommandMap\mergeToBottom(), TYPO3\CMS\Version\DataHandler\CommandMap\mergeToTop(), TYPO3\CMS\Core\Tests\Unit\Resource\BaseTestCase\mergeToVfsContents(), TYPO3\CMS\Extensionmanager\Domain\Repository\ConfigurationItemRepository\mergeWithExistingConfiguration(), TYPO3\CMS\Frontend\Controller\TypoScriptFrontendController\mergingWithGetVars(), TYPO3\CMS\Backend\Form\FlexFormsHelper\modifySingleFlexFormSheet(), TYPO3\CMS\Backend\Form\FormEngine\overrideFieldConf(), TYPO3\CMS\Extbase\Configuration\FrontendConfigurationManager\overrideStoragePidIfStartingPointIsSet(), TYPO3\CMS\Frontend\Plugin\AbstractPlugin\pi_linkTP_keepPIvars(), TYPO3\CMS\Frontend\Plugin\AbstractPlugin\pi_setPiVarDefaults(), TYPO3\CMS\Backend\Form\Element\SuggestElement\processAjaxRequest(), TYPO3\CMS\Core\TypoScript\TemplateService\processIncludes(), TYPO3\CMS\Lang\LanguageService\readLLfile(), TYPO3\CMS\Core\Page\PageRenderer\readLLfile(), TYPO3\CMS\Frontend\Controller\TypoScriptFrontendController\readLLfile(), TYPO3\CMS\Extbase\Utility\ExtensionUtility\registerModule(), TYPO3\CMS\Backend\Utility\BackendUtility\RTEsetup(), TYPO3\CMS\Core\Database\SoftReferenceIndex\setTypoLinkPartsElement(), TYPO3\CMS\Scheduler\Controller\SchedulerModuleController\stopTask(), TYPO3\CMS\Core\Tests\Unit\Resource\ResourceStorageTest\tearDown(), TYPO3\CMS\Core\Configuration\ConfigurationManager\updateLocalConfiguration(), and TYPO3\CMS\Extbase\Mvc\Web\Routing\UriBuilder\uriFor().

removeByPath()

static TYPO3\CMS\Core\Utility\ArrayUtility::removeByPath ( array  $array,   $path,   $delimiter = '/'  )

static

Remove a sub part from an array specified by path

Parameters

array	$array	Input array to manipulate
string	$path	Path to remove from array
string	$delimiter	Path delimiter

Returns

array Modified array

Exceptions

Definition at line 214 of file ArrayUtility.php.

Referenced by TYPO3\CMS\Core\Tests\Unit\Utility\ArrayUtilityTest\removeByPathAcceptsGivenDelimiter(), TYPO3\CMS\Core\Tests\Unit\Utility\ArrayUtilityTest\removeByPathRemovesCorrectPath(), TYPO3\CMS\Core\Tests\Unit\Utility\ArrayUtilityTest\removeByPathThrowsExceptionIfPathDoesNotExistInArray(), TYPO3\CMS\Core\Tests\Unit\Utility\ArrayUtilityTest\removeByPathThrowsExceptionIfPathIsEmpty(), TYPO3\CMS\Core\Tests\Unit\Utility\ArrayUtilityTest\removeByPathThrowsExceptionIfPathIsNotAString(), TYPO3\CMS\Core\Tests\Unit\Utility\ArrayUtilityTest\removeByPathThrowsExceptionWithEmptyPathSegment(), and TYPO3\CMS\Core\Configuration\ConfigurationManager\removeLocalConfigurationKeysByPath().

renumberKeysToAvoidLeapsIfKeysAreAllNumeric()

static TYPO3\CMS\Core\Utility\ArrayUtility::renumberKeysToAvoidLeapsIfKeysAreAllNumeric ( array  $array = array(),   $level = 0  )

static

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

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	Input array
integer	$level	Internal level used for recursion, do not set from outside!

Returns

array

Definition at line 475 of file ArrayUtility.php.

Referenced by TYPO3\CMS\Core\Tests\Unit\Utility\ArrayUtilityTest\renumberKeysToAvoidLeapsIfKeysAreAllNumeric(), and TYPO3\CMS\Core\Configuration\ConfigurationManager\writeLocalConfiguration().

setValueByPath()

static TYPO3\CMS\Core\Utility\ArrayUtility::setValueByPath ( array  $array,   $path,   $value,   $delimiter = '/'  )

static

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

Example:

• array: array( 'foo' => array( 'bar' => 42, ), );
• path: foo/bar
• value: 23
• return: array( 'foo' => array( 'bar' => 23, ), );

Parameters

array	$array	Input array to manipulate
string	$path	Path in array to search for
mixed	$value	Value to set at path location in array
string	$delimiter	Path delimiter

Returns

array Modified array

Exceptions

Definition at line 176 of file ArrayUtility.php.

Referenced by TYPO3\CMS\Extensionmanager\Utility\ConfigurationUtility\convertValuedToNestedConfiguration(), TYPO3\CMS\Core\Configuration\ConfigurationManager\setLocalConfigurationValueByPath(), TYPO3\CMS\Core\Configuration\ConfigurationManager\setLocalConfigurationValuesByPathValuePairs(), TYPO3\CMS\Core\Tests\Unit\Utility\ArrayUtilityTest\setValueByPathSetsCorrectValue(), TYPO3\CMS\Core\Tests\Unit\Utility\ArrayUtilityTest\setValueByPathThrowsExceptionIfPathIsEmpty(), TYPO3\CMS\Core\Tests\Unit\Utility\ArrayUtilityTest\setValueByPathThrowsExceptionIfPathIsNotAString(), and TYPO3\CMS\Core\DataHandling\DataHandler\updateFlexFormData().

sortArraysByKey()

static TYPO3\CMS\Core\Utility\ArrayUtility::sortArraysByKey ( array  $arrays,   $key,   $ascending = TRUE  )

static

Sort an array of arrays by a given key using uasort

Parameters

array	$arrays	Array of arrays to sort
string	$key	Key to sort after
bool	$ascending	Set to TRUE for ascending order, FALSE for descending order

Returns

array Array of sorted arrays

Exceptions

Definition at line 270 of file ArrayUtility.php.

Referenced by TYPO3\CMS\Core\Tests\Unit\Utility\ArrayUtilityTest\sortArraysByKeyCheckIfSortingIsCorrect(), and TYPO3\CMS\Core\Tests\Unit\Utility\ArrayUtilityTest\sortArraysByKeyThrowsExceptionForNonExistingKey().

sortByKeyRecursive()

static TYPO3\CMS\Core\Utility\ArrayUtility::sortByKeyRecursive ( array  $array )

static

Sorts an array recursively by key

Parameters

$array

Array to sort recursively by key

Returns

array Sorted array

Definition at line 251 of file ArrayUtility.php.

Referenced by TYPO3\CMS\Install\Controller\StepController\redirectToTool(), TYPO3\CMS\Core\Tests\Unit\Utility\ArrayUtilityTest\sortByKeyRecursiveCheckIfSortingIsCorrect(), and TYPO3\CMS\Core\Configuration\ConfigurationManager\writeLocalConfiguration().