ArrayUtility.php

Go to the documentation of this file.

<?php
 
/*
 * 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!
 */
 
namespace ‪TYPO3\CMS\Core\Utility;
 
use ‪TYPO3\CMS\Core\Utility\Exception\MissingArrayPathException;
 
class ‪ArrayUtility
{
    public static function ‪assertAllArrayKeysAreValid(array $arrayToTest, array $allowedArrayKeys)
    {
        $notAllowedArrayKeys = array_keys(array_diff_key($arrayToTest, array_flip($allowedArrayKeys)));
        if (count($notAllowedArrayKeys) !== 0) {
            throw new \InvalidArgumentException(
                sprintf(
                    'The options "%s" were not allowed (allowed were: "%s")',
                    implode(', ', $notAllowedArrayKeys),
                    implode(', ', $allowedArrayKeys)
                ),
                1325697085
            );
        }
    }
 
    public static function ‪convertBooleanStringsToBooleanRecursive(array $array): array
    {
        $result = $array;
        foreach ($result as $key => $value) {
            if (is_array($value)) {
                $result[$key] = ‪self::convertBooleanStringsToBooleanRecursive($value);
            } else {
                if ($value === 'true') {
                    $result[$key] = true;
                } elseif ($value === 'false') {
                    $result[$key] = false;
                }
            }
        }
        return $result;
    }
 
    public static function ‪filterByValueRecursive($needle = '', array $haystack = [])
    {
        $resultArray = [];
        // Define a lambda function to be applied to all members of this array dimension
        // Call recursive if current value is of type array
        // Write to $resultArray (by reference!) if types and value match
        $callback = function (&$value, $key) use ($needle, &$resultArray) {
            if ($value === $needle) {
                $resultArray[$key] = $value;
            } elseif (is_array($value)) {
                $subArrayMatches = static::filterByValueRecursive($needle, $value);
                if (!empty($subArrayMatches)) {
                    $resultArray[$key] = $subArrayMatches;
                }
            }
        };
        // array_walk() is not affected by the internal pointers, no need to reset
        array_walk($haystack, $callback);
        // Pointers to result array are reset internally
        return $resultArray;
    }
 
    public static function ‪isValidPath(array $array, $path, $delimiter = '/')
    {
        $isValid = true;
        try {
            static::getValueByPath($array, $path, $delimiter);
        } catch (‪MissingArrayPathException $e) {
            $isValid = false;
        }
        return $isValid;
    }
 
    public static function ‪getValueByPath(array $array, $path, $delimiter = '/')
    {
        // Extract parts of the path
        if (is_string($path)) {
            if ($path === '') {
                // Programming error has to be sanitized before calling the method -> global exception
                throw new \RuntimeException('Path must not be empty', 1341397767);
            }
            $path = str_getcsv($path, $delimiter);
        } elseif (!is_array($path)) {
            // Programming error has to be sanitized before calling the method -> global exception
            throw new \InvalidArgumentException('getValueByPath() expects $path to be string or array, "' . gettype($path) . '" given.', 1476557628);
        }
        // Loop through each part and extract its value
        $value = $array;
        foreach ($path as $segment) {
            if (is_array($value) && array_key_exists($segment, $value)) {
                // Replace current value with child
                $value = $value[$segment];
            } else {
                // Throw specific exception if there is no such path
                throw new ‪MissingArrayPathException('Segment ' . $segment . ' of path ' . implode($delimiter, $path) . ' does not exist in array', 1341397869);
            }
        }
        return $value;
    }
 
    public static function ‪reIndexNumericArrayKeysRecursive(array $array): array
    {
        if (count(array_filter(array_keys($array), 'is_string')) === 0) {
            $array = array_values($array);
        }
        foreach ($array as $key => $value) {
            if (is_array($value) && !empty($value)) {
                $array[$key] = ‪self::reIndexNumericArrayKeysRecursive($value);
            }
        }
        return $array;
    }
 
    public static function ‪removeNullValuesRecursive(array $array): array
    {
        $result = $array;
        foreach ($result as $key => $value) {
            if (is_array($value)) {
                $result[$key] = ‪self::removeNullValuesRecursive($value);
            } elseif ($value === null) {
                unset($result[$key]);
            }
        }
        return $result;
    }
 
    public static function ‪setValueByPath(array $array, $path, $value, $delimiter = '/')
    {
        if (is_string($path)) {
            if ($path === '') {
                throw new \RuntimeException('Path must not be empty', 1341406194);
            }
            // Extract parts of the path
            $path = str_getcsv($path, $delimiter);
        } elseif (!is_array($path) && !$path instanceof \ArrayAccess) {
            throw new \InvalidArgumentException('setValueByPath() expects $path to be string, array or an object implementing \\ArrayAccess, "' . (is_object($path) ? get_class($path) : gettype($path)) . '" given.', 1478781081);
        }
        // Point to the root of the array
        $pointer = &$array;
        // Find path in given array
        foreach ($path as $segment) {
            // Fail if the part is empty
            if ($segment === '') {
                throw new \RuntimeException('Invalid path segment specified', 1341406846);
            }
            // Create cell if it doesn't exist
            if (is_array($pointer) && !array_key_exists($segment, $pointer)) {
                $pointer[$segment] = [];
            }
            // Make it array if it was something else before
            if (!is_array($pointer)) {
                $pointer = [];
            }
            // Set pointer to new cell
            $pointer = &$pointer[$segment];
        }
        // Set value of target cell
        $pointer = $value;
        return $array;
    }
 
    public static function ‪removeByPath(array $array, $path, $delimiter = '/')
    {
        if (!is_string($path)) {
            throw new \RuntimeException('Path must be a string', 1371757719);
        }
        if ($path === '') {
            throw new \RuntimeException('Path must not be empty', 1371757718);
        }
        // Extract parts of the path
        $path = str_getcsv($path, $delimiter);
        $pathDepth = count($path);
        $currentDepth = 0;
        $pointer = &$array;
        // Find path in given array
        foreach ($path as $segment) {
            $currentDepth++;
            // Fail if the part is empty
            if ($segment === '') {
                throw new \RuntimeException('Invalid path segment specified', 1371757720);
            }
            if (!array_key_exists($segment, $pointer)) {
                throw new ‪MissingArrayPathException('Segment ' . $segment . ' of path ' . implode($delimiter, $path) . ' does not exist in array', 1371758436);
            }
            if ($currentDepth === $pathDepth) {
                unset($pointer[$segment]);
            } else {
                $pointer = &$pointer[$segment];
            }
        }
        return $array;
    }
 
    public static function ‪sortByKeyRecursive(array $array)
    {
        ksort($array);
        foreach ($array as $key => $value) {
            if (is_array($value) && !empty($value)) {
                $array[$key] = ‪self::sortByKeyRecursive($value);
            }
        }
        return $array;
    }
 
    public static function ‪sortArraysByKey(array $arrays, $key, $ascending = true)
    {
        if (empty($arrays)) {
            return $arrays;
        }
        $sortResult = uasort($arrays, function (array $a, array $b) use ($key, $ascending) {
            if (!isset($a[$key]) || !isset($b[$key])) {
                throw new \RuntimeException('The specified sorting key "' . $key . '" is not available in the given array.', 1373727309);
            }
            return $ascending ? strcasecmp($a[$key], $b[$key]) : strcasecmp($b[$key], $a[$key]);
        });
        if (!$sortResult) {
            throw new \RuntimeException('The function uasort() failed for unknown reasons.', 1373727329);
        }
        return $arrays;
    }
 
    public static function ‪arrayExport(array $array = [], $level = 0)
    {
        $lines = "[\n";
        $level++;
        $writeKeyIndex = false;
        $expectedKeyIndex = 0;
        foreach ($array as $key => $value) {
            if ($key === $expectedKeyIndex) {
                $expectedKeyIndex++;
            } else {
                // Found a non integer or non consecutive key, so we can break here
                $writeKeyIndex = true;
                break;
            }
        }
        foreach ($array as $key => $value) {
            // Indention
            $lines .= str_repeat('    ', $level);
            if ($writeKeyIndex) {
                // Numeric / string keys
                $lines .= is_int($key) ? $key . ' => ' : '\'' . $key . '\' => ';
            }
            if (is_array($value)) {
                if (!empty($value)) {
                    $lines .= self::arrayExport($value, $level);
                } else {
                    $lines .= "[],\n";
                }
            } elseif (is_int($value) || is_float($value)) {
                $lines .= $value . ",\n";
            } elseif ($value === null) {
                $lines .= "null,\n";
            } elseif (is_bool($value)) {
                $lines .= $value ? 'true' : 'false';
                $lines .= ",\n";
            } elseif (is_string($value)) {
                // Quote \ to \\
                // Quote ' to \'
                $stringContent = str_replace(['\\', '\''], ['\\\\', '\\\''], $value);
                $lines .= '\'' . $stringContent . "',\n";
            } else {
                throw new \RuntimeException('Objects are not supported', 1342294987);
            }
        }
        $lines .= str_repeat('    ', $level - 1) . ']' . ($level - 1 == 0 ? '' : ",\n");
        return $lines;
    }
 
    public static function ‪flatten(array $array, $prefix = '', bool $keepDots = false)
    {
        $flatArray = [];
        foreach ($array as $key => $value) {
            if ($keepDots === false) {
                // Ensure there is no trailing dot:
                $key = rtrim($key, '.');
            }
            if (!is_array($value)) {
                $flatArray[$prefix . $key] = $value;
            } else {
                $newPrefix = $prefix . $key;
                if ($keepDots === false) {
                    $newPrefix = $prefix . $key . '.';
                }
                $flatArray = array_merge($flatArray, self::flatten($value, $newPrefix, $keepDots));
            }
        }
        return $flatArray;
    }
 
    public static function ‪flattenPlain(array $array): array
    {
        $flattenRecursive = static function (array $array, string $prefix = '') use (&$flattenRecursive) {
            $flatArray[] = [];
            foreach ($array as $key => $value) {
                $key = addcslashes((string)$key, '.');
                if (!is_array($value)) {
                    $flatArray[] = [$prefix . $key => $value];
                } else {
                    $flatArray[] = $flattenRecursive($value, $prefix . $key . '.');
                }
            }
 
            return array_merge(...$flatArray);
        };
 
        return $flattenRecursive($array);
    }
 
    public static function ‪intersectRecursive(array $source, array $mask = [])
    {
        $intersection = [];
        foreach ($source as $key => $_) {
            if (!array_key_exists($key, $mask)) {
                continue;
            }
            if (is_array($source[$key]) && is_array($mask[$key])) {
                $value = ‪self::intersectRecursive($source[$key], $mask[$key]);
                if (!empty($value)) {
                    $intersection[$key] = $value;
                }
            } else {
                $intersection[$key] = $source[$key];
            }
        }
        return $intersection;
    }
 
    public static function ‪renumberKeysToAvoidLeapsIfKeysAreAllNumeric(array $array = [], $level = 0)
    {
        $level++;
        $allKeysAreNumeric = true;
        foreach ($array as $key => $_) {
            if (is_int($key) === false) {
                $allKeysAreNumeric = false;
                break;
            }
        }
        $renumberedArray = $array;
        if ($allKeysAreNumeric === true) {
            $renumberedArray = array_values($array);
        }
        foreach ($renumberedArray as $key => $value) {
            if (is_array($value)) {
                $renumberedArray[$key] = ‪self::renumberKeysToAvoidLeapsIfKeysAreAllNumeric($value, $level);
            }
        }
        return $renumberedArray;
    }
 
    public static function ‪mergeRecursiveWithOverrule(array &$original, array $overrule, $addKeys = true, $includeEmptyValues = true, $enableUnsetFeature = true)
    {
        foreach ($overrule as $key => $_) {
            if ($enableUnsetFeature && $overrule[$key] === '__UNSET') {
                unset($original[$key]);
                continue;
            }
            if (isset($original[$key]) && is_array($original[$key])) {
                if (is_array($overrule[$key])) {
                    ‪self::mergeRecursiveWithOverrule($original[$key], $overrule[$key], $addKeys, $includeEmptyValues, $enableUnsetFeature);
                }
            } elseif (
                ($addKeys || isset($original[$key])) &&
                ($includeEmptyValues || $overrule[$key])
            ) {
                $original[$key] = $overrule[$key];
            }
        }
        // This line is kept for backward compatibility reasons.
        reset($original);
    }
 
    public static function ‪removeArrayEntryByValue(array $array, $cmpValue)
    {
        foreach ($array as $k => $v) {
            if (is_array($v)) {
                $array[$k] = ‪self::removeArrayEntryByValue($v, $cmpValue);
            } elseif ((string)$v === (string)$cmpValue) {
                unset($array[$k]);
            }
        }
        return $array;
    }
 
    public static function ‪keepItemsInArray(array $array, $keepItems, $getValueFunc = null)
    {
        if ($array) {
            // Convert strings to arrays:
            if (is_string($keepItems)) {
                $keepItems = ‪GeneralUtility::trimExplode(',', $keepItems);
            }
            // Check if valueFunc can be executed:
            if (!is_callable($getValueFunc)) {
                $getValueFunc = null;
            }
            // Do the filtering:
            if (is_array($keepItems) && !empty($keepItems)) {
                $keepItems = array_flip($keepItems);
                foreach ($array as $key => $value) {
                    // Get the value to compare by using the callback function:
                    $keepValue = isset($getValueFunc) ? call_user_func($getValueFunc, $value) : $value;
                    if (!isset($keepItems[$keepValue])) {
                        unset($array[$key]);
                    }
                }
            }
        }
        return $array;
    }
 
    public static function ‪remapArrayKeys(array &$array, array $mappingTable)
    {
        foreach ($mappingTable as $old => $new) {
            if ($new && isset($array[$old])) {
                $array[$new] = $array[$old];
                unset($array[$old]);
            }
        }
    }
 
    public static function ‪arrayDiffKeyRecursive(array $array1, array $array2): array
    {
        $differenceArray = [];
        foreach ($array1 as $key => $value) {
            if (!array_key_exists($key, $array2)) {
                $differenceArray[$key] = $value;
            } elseif (is_array($value)) {
                if (is_array($array2[$key])) {
                    $recursiveResult = ‪self::arrayDiffKeyRecursive($value, $array2[$key]);
                    if (!empty($recursiveResult)) {
                        $differenceArray[$key] = $recursiveResult;
                    }
                }
            }
        }
        return $differenceArray;
    }
 
    public static function ‪arrayDiffAssocRecursive(array $array1, array $array2, bool $useArrayDiffAssocBehavior = false): array
    {
        if (!$useArrayDiffAssocBehavior) {
            return ‪self::arrayDiffKeyRecursive($array1, $array2);
        }
 
        $differenceArray = [];
        foreach ($array1 as $key => $value) {
            if (!array_key_exists($key, $array2) || (!is_array($value) && $value !== $array2[$key])) {
                $differenceArray[$key] = $value;
            } elseif (is_array($value)) {
                if (is_array($array2[$key])) {
                    $recursiveResult = ‪self::arrayDiffAssocRecursive($value, $array2[$key], $useArrayDiffAssocBehavior);
                    if (!empty($recursiveResult)) {
                        $differenceArray[$key] = $recursiveResult;
                    }
                }
            }
        }
        return $differenceArray;
    }
 
    public static function ‪naturalKeySortRecursive(array &$array)
    {
        uksort($array, 'strnatcasecmp');
        foreach ($array as $key => &$value) {
            if (is_array($value)) {
                ‪self::naturalKeySortRecursive($value);
            }
        }
 
        return true;
    }
 
    public static function ‪filterAndSortByNumericKeys($setupArr, $acceptAnyKeys = false)
    {
        $filteredKeys = [];
        $keys = array_keys($setupArr);
        foreach ($keys as $key) {
            if ($acceptAnyKeys || ‪MathUtility::canBeInterpretedAsInteger($key)) {
                $filteredKeys[] = (int)$key;
            }
        }
        $filteredKeys = array_unique($filteredKeys);
        sort($filteredKeys);
        return $filteredKeys;
    }
 
    public static function ‪sortArrayWithIntegerKeys(array $array)
    {
        if (count(array_filter(array_keys($array), 'is_string')) === 0) {
            ksort($array);
        }
        return $array;
    }
 
    public static function ‪sortArrayWithIntegerKeysRecursive(array $array): array
    {
        $array = static::sortArrayWithIntegerKeys($array);
        foreach ($array as $key => $value) {
            if (is_array($value) && !empty($value)) {
                $array[$key] = ‪self::sortArrayWithIntegerKeysRecursive($value);
            }
        }
        return $array;
    }
 
    public static function ‪stripTagsFromValuesRecursive(array $array): array
    {
        $result = $array;
        foreach ($result as $key => $value) {
            if (is_array($value)) {
                $result[$key] = ‪self::stripTagsFromValuesRecursive($value);
            } elseif (is_string($value) || (is_object($value) && method_exists($value, '__toString'))) {
                $result[$key] = strip_tags((string)$value);
            }
        }
        return $result;
    }
 
    public static function ‪filterRecursive(array $array, callable $callback = null): array
    {
        $callback = $callback ?: function ($value) {
            return (bool)$value;
        };
 
        foreach ($array as $key => $value) {
            if (is_array($value)) {
                $array[$key] = ‪self::filterRecursive($value, $callback);
            }
 
            if (!call_user_func($callback, $value)) {
                unset($array[$key]);
            }
        }
 
        return $array;
    }
 
    public static function ‪isAssociative(array $array): bool
    {
        return count(array_filter(array_keys($array), 'is_string')) > 0;
    }
 
    public static function ‪replaceAndAppendScalarValuesRecursive(array $array1, array $array2): array
    {
        // Simple lists get merged / added up
        if (!self::isAssociative($array1)) {
            return array_merge($array1, $array2);
        }
        foreach ($array1 as $k => $v) {
            // The key also exists in second array, if it is a simple value
            // then $array2 will override the value, where an array is calling
            // replaceAndAppendScalarValuesRecursive() recursively.
            if (isset($array2[$k])) {
                if (is_array($v) && is_array($array2[$k])) {
                    $array1[$k] = ‪self::replaceAndAppendScalarValuesRecursive($v, $array2[$k]);
                } else {
                    $array1[$k] = $array2[$k];
                }
                unset($array2[$k]);
            }
        }
        // If there are properties in the second array left, they are added up
        if (!empty($array2)) {
            foreach ($array2 as $k => $v) {
                $array1[$k] = $v;
            }
        }
 
        return $array1;
    }
}