CRM/Utils/Array.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | Copyright CiviCRM LLC. All rights reserved.                        |
   5  |                                                                    |
   6  | This work is published under the GNU AGPLv3 license with some      |
   7  | permitted exceptions and without any warranty. For full license    |
   8  | and copyright information, see https://civicrm.org/licensing       |
   9  +--------------------------------------------------------------------+
  10  */
  11
  12 /**
  13  * Provides a collection of static methods for array manipulation.
  14  *
  15  * @package CRM
  16  * @copyright CiviCRM LLC https://civicrm.org/licensing
  17  */
  18 class CRM_Utils_Array {
  19
  20   /**
  21    * Cast a value to an array.
  22    *
  23    * This is similar to PHP's `(array)`, but it also converts iterators.
  24    *
  25    * @param mixed $value
  26    * @return array
  27    */
  28   public static function cast($value) {
  29     if (is_array($value)) {
  30       return $value;
  31     }
  32     if ($value instanceof CRM_Utils_LazyArray || $value instanceof ArrayObject) {
  33       // iterator_to_array() would work here, but getArrayCopy() doesn't require actual iterations.
  34       return $value->getArrayCopy();
  35     }
  36     if (is_iterable($value)) {
  37       return iterator_to_array($value);
  38     }
  39     if (is_scalar($value)) {
  40       return [$value];
  41     }
  42     throw new \RuntimeException(sprintf("Cannot cast %s to array", gettype($value)));
  43   }
  44
  45   /**
  46    * Returns $list[$key] if such element exists, or a default value otherwise.
  47    *
  48    * If $list is not actually an array at all, then the default value is
  49    * returned. We hope to deprecate this behaviour.
  50    *
  51    *
  52    * @param string $key
  53    *   Key value to look up in the array.
  54    * @param array|ArrayAccess $list
  55    *   Array from which to look up a value.
  56    * @param mixed $default
  57    *   (optional) Value to return $list[$key] does not exist.
  58    *
  59    * @return mixed
  60    *   Can return any type, since $list might contain anything.
  61    */
  62   public static function value($key, $list, $default = NULL) {
  63     if (is_array($list)) {
  64       return array_key_exists($key, $list) ? $list[$key] : $default;
  65     }
  66     if ($list instanceof ArrayAccess) {
  67       // ArrayAccess requires offsetExists is implemented for the equivalent to array_key_exists.
  68       return $list->offsetExists($key) ? $list[$key] : $default;
  69     }
  70     // @todo - eliminate these from core & uncomment this line.
  71     // CRM_Core_Error::deprecatedFunctionWarning('You have passed an invalid parameter for the "list"');
  72     return $default;
  73   }
  74
  75   /**
  76    * Recursively searches an array for a key, returning the first value found.
  77    *
  78    * If $params[$key] does not exist and $params contains arrays, descend into
  79    * each array in a depth-first manner, in array iteration order.
  80    *
  81    * @param array $params
  82    *   The array to be searched.
  83    * @param string $key
  84    *   The key to search for.
  85    *
  86    * @return mixed
  87    *   The value of the key, or null if the key is not found.
  88    */
  89   public static function retrieveValueRecursive(array $params, string $key) {
  90     // Note that !empty means funky handling for 0
  91     // but it is 'baked in'. We should probably deprecate this
  92     // for a more logical approach.
  93     // see https://github.com/civicrm/civicrm-core/pull/19478#issuecomment-785388559
  94     if (!empty($params[$key])) {
  95       return $params[$key];
  96     }
  97     foreach ($params as $subParam) {
  98       if (is_array($subParam) &&
  99         // @todo - this will mishandle values like 0 and false
 100         // but it's a little scary to fix.
 101         $value = self::retrieveValueRecursive($subParam, $key)
 102       ) {
 103         return $value;
 104       }
 105     }
 106     return NULL;
 107   }
 108
 109   /**
 110    * Recursively searches through a given array for all matches
 111    *
 112    * @param $collection
 113    * @param $predicate
 114    * @return array
 115    */
 116   public static function findAll($collection, $predicate) {
 117     $results = [];
 118     $search = function($collection) use (&$search, &$results, $predicate) {
 119       if (is_array($collection)) {
 120         if (is_callable($predicate)) {
 121           if ($predicate($collection)) {
 122             $results[] = $collection;
 123           }
 124         }
 125         elseif (is_array($predicate)) {
 126           if (count(array_intersect_assoc($collection, $predicate)) === count($predicate)) {
 127             $results[] = $collection;
 128           }
 129         }
 130         else {
 131           if (array_key_exists($predicate, $collection)) {
 132             $results[] = $collection;
 133           }
 134         }
 135         foreach ($collection as $item) {
 136           $search($item);
 137         }
 138       }
 139     };
 140     $search($collection);
 141     return $results;
 142   }
 143
 144   /**
 145    * Wraps and slightly changes the behavior of PHP's array_search().
 146    *
 147    * This function reproduces the behavior of array_search() from PHP prior to
 148    * version 4.2.0, which was to return NULL on failure. This function also
 149    * checks that $list is an array before attempting to search it.
 150    *
 151    *
 152    * @param mixed $value
 153    *   The value to search for.
 154    * @param array $list
 155    *   The array to be searched.
 156    *
 157    * @return int|string|null
 158    *   Returns the key, which could be an int or a string, or NULL on failure.
 159    */
 160   public static function key($value, $list) {
 161     if (is_array($list)) {
 162       $key = array_search($value, $list);
 163
 164       // array_search returns key if found, false otherwise
 165       // it may return values like 0 or empty string which
 166       // evaluates to false
 167       // hence we must use identical comparison operator
 168       return ($key === FALSE) ? NULL : $key;
 169     }
 170     return NULL;
 171   }
 172
 173   /**
 174    * Builds an XML fragment representing an array.
 175    *
 176    * Depending on the nature of the keys of the array (and its sub-arrays,
 177    * if any) the XML fragment may not be valid.
 178    *
 179    * @param array $list
 180    *   The array to be serialized.
 181    * @param int $depth
 182    *   (optional) Indentation depth counter.
 183    * @param string $separator
 184    *   (optional) String to be appended after open/close tags.
 185    *
 186    * @return string
 187    *   XML fragment representing $list.
 188    */
 189   public static function &xml(&$list, $depth = 1, $separator = "\n") {
 190     $xml = '';
 191     foreach ($list as $name => $value) {
 192       $xml .= str_repeat(' ', $depth * 4);
 193       if (is_array($value)) {
 194         $xml .= "<{$name}>{$separator}";
 195         $xml .= self::xml($value, $depth + 1, $separator);
 196         $xml .= str_repeat(' ', $depth * 4);
 197         $xml .= "</{$name}>{$separator}";
 198       }
 199       else {
 200         // make sure we escape value
 201         $value = self::escapeXML($value);
 202         $xml .= "<{$name}>$value</{$name}>{$separator}";
 203       }
 204     }
 205     return $xml;
 206   }
 207
 208   /**
 209    * Sanitizes a string for serialization in CRM_Utils_Array::xml().
 210    *
 211    * Replaces '&', '<', and '>' with their XML escape sequences. Replaces '^A'
 212    * with a comma.
 213    *
 214    * @param string $value
 215    *   String to be sanitized.
 216    *
 217    * @return string
 218    *   Sanitized version of $value.
 219    */
 220   public static function escapeXML($value) {
 221     static $src = NULL;
 222     static $dst = NULL;
 223
 224     if (!$src) {
 225       $src = ['&', '<', '>', '\ 1'];
 226       $dst = ['&amp;', '&lt;', '&gt;', ','];
 227     }
 228
 229     return str_replace($src, $dst, $value);
 230   }
 231
 232   /**
 233    * Converts a nested array to a flat array.
 234    *
 235    * The nested structure is preserved in the string values of the keys of the
 236    * flat array.
 237    *
 238    * Example nested array:
 239    * Array
 240    * (
 241    *     [foo] => Array
 242    *         (
 243    *             [0] => bar
 244    *             [1] => baz
 245    *             [2] => 42
 246    *         )
 247    *
 248    *     [asdf] => Array
 249    *         (
 250    *             [merp] => bleep
 251    *             [quack] => Array
 252    *                 (
 253    *                     [0] => 1
 254    *                     [1] => 2
 255    *                     [2] => 3
 256    *                 )
 257    *
 258    *         )
 259    *
 260    *     [quux] => 999
 261    * )
 262    *
 263    * Corresponding flattened array:
 264    * Array
 265    * (
 266    *     [foo.0] => bar
 267    *     [foo.1] => baz
 268    *     [foo.2] => 42
 269    *     [asdf.merp] => bleep
 270    *     [asdf.quack.0] => 1
 271    *     [asdf.quack.1] => 2
 272    *     [asdf.quack.2] => 3
 273    *     [quux] => 999
 274    * )
 275    *
 276    * @param array $list
 277    *   Array to be flattened.
 278    * @param array $flat
 279    *   Destination array.
 280    * @param string $prefix
 281    *   (optional) String to prepend to keys.
 282    * @param string $separator
 283    *   (optional) String that separates the concatenated keys.
 284    */
 285   public static function flatten(&$list, &$flat, $prefix = '', $separator = ".") {
 286     foreach ($list as $name => $value) {
 287       $newPrefix = ($prefix) ? $prefix . $separator . $name : $name;
 288       if (is_array($value)) {
 289         self::flatten($value, $flat, $newPrefix, $separator);
 290       }
 291       else {
 292         $flat[$newPrefix] = $value;
 293       }
 294     }
 295   }
 296
 297   /**
 298    * Converts an array with path-like keys into a tree of arrays.
 299    *
 300    * This function is the inverse of CRM_Utils_Array::flatten().
 301    *
 302    * @param string $delim
 303    *   A path delimiter
 304    * @param array $arr
 305    *   A one-dimensional array indexed by string keys
 306    *
 307    * @return array
 308    *   Array-encoded tree
 309    */
 310   public function unflatten($delim, &$arr) {
 311     $result = [];
 312     foreach ($arr as $key => $value) {
 313       $path = explode($delim, $key);
 314       $node = &$result;
 315       while (count($path) > 1) {
 316         $key = array_shift($path);
 317         if (!isset($node[$key])) {
 318           $node[$key] = [];
 319         }
 320         $node = &$node[$key];
 321       }
 322       // last part of path
 323       $key = array_shift($path);
 324       $node[$key] = $value;
 325     }
 326     return $result;
 327   }
 328
 329   /**
 330    * Merges two arrays.
 331    *
 332    * If $a1[foo] and $a2[foo] both exist and are both arrays, the merge
 333    * process recurses into those sub-arrays. If $a1[foo] and $a2[foo] both
 334    * exist but they are not both arrays, the value from $a1 overrides the
 335    * value from $a2 and the value from $a2 is discarded.
 336    *
 337    * @param array $a1
 338    *   First array to be merged.
 339    * @param array $a2
 340    *   Second array to be merged.
 341    *
 342    * @return array
 343    *   The merged array.
 344    */
 345   public static function crmArrayMerge($a1, $a2) {
 346     if (empty($a1)) {
 347       return $a2;
 348     }
 349
 350     if (empty($a2)) {
 351       return $a1;
 352     }
 353
 354     $a3 = [];
 355     foreach ($a1 as $key => $value) {
 356       if (array_key_exists($key, $a2) &&
 357         is_array($a2[$key]) && is_array($a1[$key])
 358       ) {
 359         $a3[$key] = array_merge($a1[$key], $a2[$key]);
 360       }
 361       else {
 362         $a3[$key] = $a1[$key];
 363       }
 364     }
 365
 366     foreach ($a2 as $key => $value) {
 367       if (array_key_exists($key, $a1)) {
 368         // already handled in above loop
 369         continue;
 370       }
 371       $a3[$key] = $a2[$key];
 372     }
 373
 374     return $a3;
 375   }
 376
 377   /**
 378    * Determines whether an array contains any sub-arrays.
 379    *
 380    * @param array $list
 381    *   The array to inspect.
 382    *
 383    * @return bool
 384    *   True if $list contains at least one sub-array, false otherwise.
 385    */
 386   public static function isHierarchical(&$list) {
 387     foreach ($list as $n => $v) {
 388       if (is_array($v)) {
 389         return TRUE;
 390       }
 391     }
 392     return FALSE;
 393   }
 394
 395   /**
 396    * Is array A a subset of array B.
 397    *
 398    * @param array $subset
 399    * @param array $superset
 400    *
 401    * @return bool
 402    *   TRUE if $subset is a subset of $superset
 403    */
 404   public static function isSubset($subset, $superset) {
 405     foreach ($subset as $expected) {
 406       if (!in_array($expected, $superset)) {
 407         return FALSE;
 408       }
 409     }
 410     return TRUE;
 411   }
 412
 413   /**
 414    * Searches an array recursively in an optionally case-insensitive manner.
 415    *
 416    * @param string $value
 417    *   Value to search for.
 418    * @param array $params
 419    *   Array to search within.
 420    * @param bool $caseInsensitive
 421    *   (optional) Whether to search in a case-insensitive manner.
 422    *
 423    * @return bool
 424    *   True if $value was found, false otherwise.
 425    */
 426   public static function crmInArray($value, $params, $caseInsensitive = TRUE) {
 427     foreach ($params as $item) {
 428       if (is_array($item)) {
 429         $ret = self::crmInArray($value, $item, $caseInsensitive);
 430       }
 431       else {
 432         $ret = ($caseInsensitive) ? strtolower($item) == strtolower($value) : $item == $value;
 433         if ($ret) {
 434           return $ret;
 435         }
 436       }
 437     }
 438     return FALSE;
 439   }
 440
 441   /**
 442    * Convert associative array names to values and vice-versa.
 443    *
 444    * This function is used by by import functions and some webforms.
 445    *
 446    * @param array $defaults
 447    * @param string $property
 448    * @param $lookup
 449    * @param $reverse
 450    *
 451    * @return bool
 452    */
 453   public static function lookupValue(&$defaults, $property, $lookup, $reverse) {
 454     $id = $property . '_id';
 455
 456     $src = $reverse ? $property : $id;
 457     $dst = $reverse ? $id : $property;
 458
 459     if (!array_key_exists(strtolower($src), array_change_key_case($defaults, CASE_LOWER))) {
 460       return FALSE;
 461     }
 462
 463     $look = $reverse ? array_flip($lookup) : $lookup;
 464
 465     // trim lookup array, ignore . ( fix for CRM-1514 ), eg for prefix/suffix make sure Dr. and Dr both are valid
 466     $newLook = [];
 467     foreach ($look as $k => $v) {
 468       $newLook[trim($k, ".")] = $v;
 469     }
 470
 471     $look = $newLook;
 472
 473     if (is_array($look)) {
 474       if (!array_key_exists(trim(strtolower($defaults[strtolower($src)]), '.'), array_change_key_case($look, CASE_LOWER))) {
 475         return FALSE;
 476       }
 477     }
 478
 479     $tempLook = array_change_key_case($look, CASE_LOWER);
 480
 481     $defaults[$dst] = $tempLook[trim(strtolower($defaults[strtolower($src)]), '.')];
 482     return TRUE;
 483   }
 484
 485   /**
 486    * Checks whether an array is empty.
 487    *
 488    * An array is empty if its values consist only of NULL and empty sub-arrays.
 489    * Containing a non-NULL value or non-empty array makes an array non-empty.
 490    *
 491    * If something other than an array is passed, it is considered to be empty.
 492    *
 493    * If nothing is passed at all, the default value provided is empty.
 494    *
 495    * @param array $array
 496    *   (optional) Array to be checked for emptiness.
 497    *
 498    * @return bool
 499    *   True if the array is empty.
 500    */
 501   public static function crmIsEmptyArray($array = []) {
 502     if (!is_array($array)) {
 503       return TRUE;
 504     }
 505     foreach ($array as $element) {
 506       if (is_array($element)) {
 507         if (!self::crmIsEmptyArray($element)) {
 508           return FALSE;
 509         }
 510       }
 511       elseif (isset($element)) {
 512         return FALSE;
 513       }
 514     }
 515     return TRUE;
 516   }
 517
 518   /**
 519    * Sorts an associative array of arrays by an attribute using strnatcmp().
 520    *
 521    * @param array $array
 522    *   Array to be sorted.
 523    * @param string|array $field
 524    *   Name of the attribute used for sorting.
 525    *
 526    * @return array
 527    *   Sorted array
 528    */
 529   public static function crmArraySortByField($array, $field) {
 530     $fields = (array) $field;
 531     uasort($array, function ($a, $b) use ($fields) {
 532       foreach ($fields as $f) {
 533         $v = strnatcmp($a[$f], $b[$f]);
 534         if ($v !== 0) {
 535           return $v;
 536         }
 537       }
 538       return 0;
 539     });
 540     return $array;
 541   }
 542
 543   /**
 544    * Recursively removes duplicate values from a multi-dimensional array.
 545    *
 546    * @param array $array
 547    *   The input array possibly containing duplicate values.
 548    *
 549    * @return array
 550    *   The input array with duplicate values removed.
 551    */
 552   public static function crmArrayUnique($array) {
 553     $result = array_map("unserialize", array_unique(array_map("serialize", $array)));
 554     foreach ($result as $key => $value) {
 555       if (is_array($value)) {
 556         $result[$key] = self::crmArrayUnique($value);
 557       }
 558     }
 559     return $result;
 560   }
 561
 562   /**
 563    * Sorts an array and maintains index association (with localization).
 564    *
 565    * Uses Collate from the PECL "intl" package, if available, for UTF-8
 566    * sorting (e.g. list of countries). Otherwise calls PHP's asort().
 567    *
 568    * On Debian/Ubuntu: apt-get install php5-intl
 569    *
 570    * @param array $array
 571    *   (optional) Array to be sorted.
 572    *
 573    * @return array
 574    *   Sorted array.
 575    */
 576   public static function asort($array = []) {
 577     $lcMessages = CRM_Utils_System::getUFLocale();
 578
 579     if ($lcMessages && $lcMessages != 'en_US' && class_exists('Collator')) {
 580       $collator = new Collator($lcMessages . '.utf8');
 581       $collator->asort($array);
 582     }
 583     else {
 584       // This calls PHP's built-in asort().
 585       asort($array);
 586     }
 587
 588     return $array;
 589   }
 590
 591   /**
 592    * Unsets an arbitrary list of array elements from an associative array.
 593    *
 594    * @param array $items
 595    *   The array from which to remove items.
 596    *
 597    * Additional params:
 598    *   When passed a string, unsets $items[$key].
 599    *   When passed an array of strings, unsets $items[$k] for each string $k in the array.
 600    */
 601   public static function remove(&$items) {
 602     foreach (func_get_args() as $n => $key) {
 603       // Skip argument 0 ($items) by testing $n for truth.
 604       if ($n && is_array($key)) {
 605         foreach ($key as $k) {
 606           unset($items[$k]);
 607         }
 608       }
 609       elseif ($n) {
 610         unset($items[$key]);
 611       }
 612     }
 613   }
 614
 615   /**
 616    * Builds an array-tree which indexes the records in an array.
 617    *
 618    * @param string[] $keys
 619    *   Properties by which to index.
 620    * @param object|array $records
 621    *
 622    * @return array
 623    *   Multi-dimensional array, with one layer for each key.
 624    */
 625   public static function index($keys, $records) {
 626     $final_key = array_pop($keys);
 627
 628     $result = [];
 629     foreach ($records as $record) {
 630       $node = &$result;
 631       foreach ($keys as $key) {
 632         if (is_array($record)) {
 633           $keyvalue = $record[$key] ?? NULL;
 634         }
 635         else {
 636           $keyvalue = $record->{$key} ?? NULL;
 637         }
 638         if (isset($node[$keyvalue]) && !is_array($node[$keyvalue])) {
 639           $node[$keyvalue] = [];
 640         }
 641         $node = &$node[$keyvalue];
 642       }
 643       if (is_array($record)) {
 644         $node[$record[$final_key]] = $record;
 645       }
 646       else {
 647         $node[$record->{$final_key}] = $record;
 648       }
 649     }
 650     return $result;
 651   }
 652
 653   /**
 654    * Iterates over a list of records and returns the value of some property.
 655    *
 656    * @param string $prop
 657    *   Property to retrieve.
 658    * @param array|object $records
 659    *   A list of records.
 660    *
 661    * @return array
 662    *   Keys are the original keys of $records; values are the $prop values.
 663    */
 664   public static function collect($prop, $records) {
 665     $result = [];
 666     if (is_array($records)) {
 667       foreach ($records as $key => $record) {
 668         if (is_object($record)) {
 669           $result[$key] = $record->{$prop};
 670         }
 671         else {
 672           $result[$key] = self::value($prop, $record);
 673         }
 674       }
 675     }
 676     return $result;
 677   }
 678
 679   /**
 680    * Iterates over a list of objects and executes some method on each.
 681    *
 682    * Comparison:
 683    *   - This is like array_map(), except it executes the objects' method
 684    *     instead of a free-form callable.
 685    *   - This is like Array::collect(), except it uses a method
 686    *     instead of a property.
 687    *
 688    * @param string $method
 689    *   The method to execute.
 690    * @param array|Traversable $objects
 691    *   A list of objects.
 692    * @param array $args
 693    *   An optional list of arguments to pass to the method.
 694    *
 695    * @return array
 696    *   Keys are the original keys of $objects; values are the method results.
 697    */
 698   public static function collectMethod($method, $objects, $args = []) {
 699     $result = [];
 700     if (is_array($objects)) {
 701       foreach ($objects as $key => $object) {
 702         $result[$key] = call_user_func_array([$object, $method], $args);
 703       }
 704     }
 705     return $result;
 706   }
 707
 708   /**
 709    * Trims delimiters from a string and then splits it using explode().
 710    *
 711    * This method works mostly like PHP's built-in explode(), except that
 712    * surrounding delimiters are trimmed before explode() is called.
 713    *
 714    * Also, if an array or NULL is passed as the $values parameter, the value is
 715    * returned unmodified rather than being passed to explode().
 716    *
 717    * @param array|null|string $values
 718    *   The input string (or an array, or NULL).
 719    * @param string $delim
 720    *   (optional) The boundary string.
 721    *
 722    * @return array|null
 723    *   An array of strings produced by explode(), or the unmodified input
 724    *   array, or NULL.
 725    */
 726   public static function explodePadded($values, $delim = CRM_Core_DAO::VALUE_SEPARATOR) {
 727     if ($values === NULL) {
 728       return NULL;
 729     }
 730     // If we already have an array, no need to continue
 731     if (is_array($values)) {
 732       return $values;
 733     }
 734     // Empty string -> empty array
 735     if ($values === '') {
 736       return [];
 737     }
 738     return explode($delim, trim((string) $values, $delim));
 739   }
 740
 741   /**
 742    * Joins array elements with a string, adding surrounding delimiters.
 743    *
 744    * This method works mostly like PHP's built-in implode(), but the generated
 745    * string is surrounded by delimiter characters. Also, if NULL is passed as
 746    * the $values parameter, NULL is returned.
 747    *
 748    * @param mixed $values
 749    *   Array to be imploded. If a non-array is passed, it will be cast to an
 750    *   array.
 751    * @param string $delim
 752    *   Delimiter to be used for implode() and which will surround the output
 753    *   string.
 754    *
 755    * @return string|NULL
 756    *   The generated string, or NULL if NULL was passed as $values parameter.
 757    */
 758   public static function implodePadded($values, $delim = CRM_Core_DAO::VALUE_SEPARATOR) {
 759     if ($values === NULL) {
 760       return NULL;
 761     }
 762     // If we already have a string, strip $delim off the ends so it doesn't get added twice
 763     if (is_string($values)) {
 764       $values = trim($values, $delim);
 765     }
 766     return $delim . implode($delim, (array) $values) . $delim;
 767   }
 768
 769   /**
 770    * Modifies a key in an array while preserving the key order.
 771    *
 772    * By default when an element is added to an array, it is added to the end.
 773    * This method allows for changing an existing key while preserving its
 774    * position in the array.
 775    *
 776    * The array is both modified in-place and returned.
 777    *
 778    * @param array $elementArray
 779    *   Array to manipulate.
 780    * @param string $oldKey
 781    *   Old key to be replaced.
 782    * @param string $newKey
 783    *   Replacement key string.
 784    *
 785    * @throws Exception
 786    *   Throws a generic Exception if $oldKey is not found in $elementArray.
 787    *
 788    * @return array
 789    *   The manipulated array.
 790    */
 791   public static function crmReplaceKey(&$elementArray, $oldKey, $newKey) {
 792     $keys = array_keys($elementArray);
 793     if (FALSE === $index = array_search($oldKey, $keys)) {
 794       throw new Exception(sprintf('key "%s" does not exit', $oldKey));
 795     }
 796     $keys[$index] = $newKey;
 797     $elementArray = array_combine($keys, array_values($elementArray));
 798     return $elementArray;
 799   }
 800
 801   /**
 802    * Searches array keys by regex, returning the value of the first match.
 803    *
 804    * Given a regular expression and an array, this method searches the keys
 805    * of the array using the regular expression. The first match is then used
 806    * to index into the array, and the associated value is retrieved and
 807    * returned. If no matches are found, or if something other than an array
 808    * is passed, then a default value is returned. Unless otherwise specified,
 809    * the default value is NULL.
 810    *
 811    * @param string $regexKey
 812    *   The regular expression to use when searching for matching keys.
 813    * @param array $list
 814    *   The array whose keys will be searched.
 815    * @param mixed $default
 816    *   (optional) The default value to return if the regex does not match an
 817    *   array key, or if something other than an array is passed.
 818    *
 819    * @return mixed
 820    *   The value found.
 821    */
 822   public static function valueByRegexKey($regexKey, $list, $default = NULL) {
 823     if (is_array($list) && $regexKey) {
 824       $matches = preg_grep($regexKey, array_keys($list));
 825       $key = reset($matches);
 826       return ($key && array_key_exists($key, $list)) ? $list[$key] : $default;
 827     }
 828     return $default;
 829   }
 830
 831   /**
 832    * Generates the Cartesian product of zero or more vectors.
 833    *
 834    * @param array $dimensions
 835    *   List of dimensions to multiply.
 836    *   Each key is a dimension name; each value is a vector.
 837    * @param array $template
 838    *   (optional) A base set of values included in every output.
 839    *
 840    * @return array
 841    *   Each item is a distinct combination of values from $dimensions.
 842    *
 843    *   For example, the product of
 844    *   {
 845    *   fg => {red, blue},
 846    *   bg => {white, black}
 847    *   }
 848    *   would be
 849    *   {
 850    *   {fg => red, bg => white},
 851    *   {fg => red, bg => black},
 852    *   {fg => blue, bg => white},
 853    *   {fg => blue, bg => black}
 854    *   }
 855    */
 856   public static function product($dimensions, $template = []) {
 857     if (empty($dimensions)) {
 858       return [$template];
 859     }
 860
 861     foreach ($dimensions as $key => $value) {
 862       $firstKey = $key;
 863       $firstValues = $value;
 864       break;
 865     }
 866     unset($dimensions[$key]);
 867
 868     $results = [];
 869     foreach ($firstValues as $firstValue) {
 870       foreach (self::product($dimensions, $template) as $result) {
 871         $result[$firstKey] = $firstValue;
 872         $results[] = $result;
 873       }
 874     }
 875
 876     return $results;
 877   }
 878
 879   /**
 880    * Get the first element of an array.
 881    *
 882    * @param array $array
 883    * @return mixed|NULL
 884    */
 885   public static function first($array) {
 886     foreach ($array as $value) {
 887       return $value;
 888     }
 889     return NULL;
 890   }
 891
 892   /**
 893    * Extract any $keys from $array and copy to a new array.
 894    *
 895    * Note: If a $key does not appear in $array, then it will
 896    * not appear in the result.
 897    *
 898    * @param array $array
 899    * @param array $keys
 900    *   List of keys to copy.
 901    * @return array
 902    */
 903   public static function subset($array, $keys) {
 904     $result = [];
 905     foreach ($keys as $key) {
 906       if (isset($array[$key])) {
 907         $result[$key] = $array[$key];
 908       }
 909     }
 910     return $result;
 911   }
 912
 913   /**
 914    * Transform an associative array of key=>value pairs into a non-associative array of arrays.
 915    * This is necessary to preserve sort order when sending an array through json_encode.
 916    *
 917    * @param array $associative
 918    *   Ex: ['foo' => 'bar'].
 919    * @param string $keyName
 920    *   Ex: 'key'.
 921    * @param string $valueName
 922    *   Ex: 'value'.
 923    * @return array
 924    *   Ex: [0 => ['key' => 'foo', 'value' => 'bar']].
 925    */
 926   public static function makeNonAssociative($associative, $keyName = 'key', $valueName = 'value') {
 927     $output = [];
 928     foreach ($associative as $key => $val) {
 929       $output[] = [$keyName => $key, $valueName => $val];
 930     }
 931     return $output;
 932   }
 933
 934   /**
 935    * Diff multidimensional arrays
 936    * (array_diff does not support multidimensional array)
 937    *
 938    * @param array $array1
 939    * @param array $array2
 940    * @return array
 941    */
 942   public static function multiArrayDiff($array1, $array2) {
 943     $arrayDiff = [];
 944     foreach ($array1 as $mKey => $mValue) {
 945       if (array_key_exists($mKey, $array2)) {
 946         if (is_array($mValue)) {
 947           $recursiveDiff = self::multiArrayDiff($mValue, $array2[$mKey]);
 948           if (count($recursiveDiff)) {
 949             $arrayDiff[$mKey] = $recursiveDiff;
 950           }
 951         }
 952         else {
 953           if ($mValue != $array2[$mKey]) {
 954             $arrayDiff[$mKey] = $mValue;
 955           }
 956         }
 957       }
 958       else {
 959         $arrayDiff[$mKey] = $mValue;
 960       }
 961     }
 962     return $arrayDiff;
 963   }
 964
 965   /**
 966    * Given a 2-dimensional matrix, create a new matrix with a restricted list of columns.
 967    *
 968    * @param array $matrix
 969    *   All matrix data, as a list of rows.
 970    * @param array $columns
 971    *   List of column names.
 972    * @return array
 973    */
 974   public static function filterColumns($matrix, $columns) {
 975     $newRows = [];
 976     foreach ($matrix as $pos => $oldRow) {
 977       $newRow = [];
 978       foreach ($columns as $column) {
 979         $newRow[$column] = $oldRow[$column] ?? NULL;
 980       }
 981       $newRows[$pos] = $newRow;
 982     }
 983     return $newRows;
 984   }
 985
 986   /**
 987    * Rotate a matrix, converting from row-oriented array to a column-oriented array.
 988    *
 989    * @param iterable $rows
 990    *   Ex: [['a'=>10,'b'=>'11'], ['a'=>20,'b'=>21]]
 991    *   Formula: [scalar $rowId => [scalar $colId => mixed $value]]
 992    * @param bool $unique
 993    *   Only return unique values.
 994    * @return array
 995    *   Ex: ['a'=>[10,20], 'b'=>[11,21]]
 996    *   Formula: [scalar $colId => [scalar $rowId => mixed $value]]
 997    *   Note: In unique mode, the $rowId is not meaningful.
 998    */
 999   public static function asColumns(iterable $rows, bool $unique = FALSE) {
1000     $columns = [];
1001     foreach ($rows as $rowKey => $row) {
1002       foreach ($row as $columnKey => $value) {
1003         if (FALSE === $unique) {
1004           $columns[$columnKey][$rowKey] = $value;
1005         }
1006         elseif (!in_array($value, $columns[$columnKey] ?? [])) {
1007           $columns[$columnKey][] = $value;
1008         }
1009       }
1010     }
1011     return $columns;
1012   }
1013
1014   /**
1015    * Rewrite the keys in an array.
1016    *
1017    * @param array $array
1018    * @param string|callable $indexBy
1019    *   Either the value to key by, or a function($key, $value) that returns the new key.
1020    * @return array
1021    */
1022   public static function rekey($array, $indexBy) {
1023     $result = [];
1024     foreach ($array as $key => $value) {
1025       $newKey = is_callable($indexBy) ? $indexBy($key, $value) : $value[$indexBy];
1026       $result[$newKey] = $value;
1027     }
1028     return $result;
1029   }
1030
1031   /**
1032    * Copy all properties of $other into $array (recursively).
1033    *
1034    * @param array|ArrayAccess $array
1035    * @param array $other
1036    */
1037   public static function extend(&$array, $other) {
1038     foreach ($other as $key => $value) {
1039       if (is_array($value)) {
1040         self::extend($array[$key], $value);
1041       }
1042       else {
1043         $array[$key] = $value;
1044       }
1045     }
1046   }
1047
1048   /**
1049    * Get a single value from an array-tree.
1050    *
1051    * @param array $values
1052    *   Ex: ['foo' => ['bar' => 123]].
1053    * @param array $path
1054    *   Ex: ['foo', 'bar'].
1055    * @param mixed $default
1056    * @return mixed
1057    *   Ex 123.
1058    */
1059   public static function pathGet($values, $path, $default = NULL) {
1060     foreach ($path as $key) {
1061       if (!is_array($values) || !isset($values[$key])) {
1062         return $default;
1063       }
1064       $values = $values[$key];
1065     }
1066     return $values;
1067   }
1068
1069   /**
1070    * Check if a key isset which may be several layers deep.
1071    *
1072    * This is a helper for when the calling function does not know how many layers deep
1073    * the path array is so cannot easily check.
1074    *
1075    * @param array $values
1076    * @param array $path
1077    * @return bool
1078    */
1079   public static function pathIsset($values, $path) {
1080     foreach ($path as $key) {
1081       if (!is_array($values) || !isset($values[$key])) {
1082         return FALSE;
1083       }
1084       $values = $values[$key];
1085     }
1086     return TRUE;
1087   }
1088
1089   /**
1090    * Remove a key from an array.
1091    *
1092    * This is a helper for when the calling function does not know how many layers deep
1093    * the path array is so cannot easily check.
1094    *
1095    * @param array $values
1096    * @param array $path
1097    * @param bool $cleanup
1098    *   If removed item leaves behind an empty array, should you remove the empty array?
1099    * @return bool
1100    *   TRUE if anything has been removed. FALSE if no changes were required.
1101    */
1102   public static function pathUnset(&$values, $path, $cleanup = FALSE) {
1103     if (count($path) === 1) {
1104       if (isset($values[$path[0]])) {
1105         unset($values[$path[0]]);
1106         return TRUE;
1107       }
1108       else {
1109         return FALSE;
1110       }
1111     }
1112     else {
1113       $next = array_shift($path);
1114       $r = static::pathUnset($values[$next], $path, $cleanup);
1115       if ($cleanup && $values[$next] === []) {
1116         $r = TRUE;
1117         unset($values[$next]);
1118       }
1119       return $r;
1120     }
1121   }
1122
1123   /**
1124    * Set a single value in an array tree.
1125    *
1126    * @param array $values
1127    *   Ex: ['foo' => ['bar' => 123]].
1128    * @param array $pathParts
1129    *   Ex: ['foo', 'bar'].
1130    * @param $value
1131    *   Ex: 456.
1132    */
1133   public static function pathSet(&$values, $pathParts, $value) {
1134     $r = &$values;
1135     $last = array_pop($pathParts);
1136     foreach ($pathParts as $part) {
1137       if (!isset($r[$part])) {
1138         $r[$part] = [];
1139       }
1140       $r = &$r[$part];
1141     }
1142     $r[$last] = $value;
1143   }
1144
1145   /**
1146    * Move an item in an array-tree (if it exists).
1147    *
1148    * @param array $values
1149    *   Data-tree
1150    * @param string[] $src
1151    *   Old path for the existing item
1152    * @param string[] $dest
1153    *   New path
1154    * @param bool $cleanup
1155    * @return int
1156    *   Number of items moved (0 or 1).
1157    */
1158   public static function pathMove(&$values, $src, $dest, $cleanup = FALSE) {
1159     if (!static::pathIsset($values, $src)) {
1160       return 0;
1161     }
1162     else {
1163       $value = static::pathGet($values, $src);
1164       static::pathSet($values, $dest, $value);
1165       static::pathUnset($values, $src, $cleanup);
1166       return 1;
1167     }
1168   }
1169
1170   /**
1171    * Attempt to synchronize or fill aliased items.
1172    *
1173    * If $canonPath is set, copy to $altPath; or...
1174    * If $altPath is set, copy to $canonPath.
1175    *
1176    * @param array $params
1177    *   Data-tree
1178    * @param string[] $canonPath
1179    *   Preferred path
1180    * @param string[] $altPath
1181    *   Old/alternate/deprecated path.
1182    * @param callable|null $filter
1183    *   Optional function to filter the value as it passes through (canonPath=>altPath or altPath=>canonPath).
1184    *   function(mixed $v, bool $isCanon): mixed
1185    */
1186   public static function pathSync(&$params, $canonPath, $altPath, ?callable $filter = NULL) {
1187     $MISSING = new \stdClass();
1188
1189     $v = static::pathGet($params, $canonPath, $MISSING);
1190     if ($v !== $MISSING) {
1191       static::pathSet($params, $altPath, $filter ? $filter($v, TRUE) : $v);
1192       return;
1193     }
1194
1195     $v = static::pathGet($params, $altPath, $MISSING);
1196     if ($v !== $MISSING) {
1197       static::pathSet($params, $canonPath, $filter ? $filter($v, FALSE) : $v);
1198       return;
1199     }
1200   }
1201
1202   /**
1203    * Convert a simple dictionary into separate key+value records.
1204    *
1205    * @param array $array
1206    *   Ex: array('foo' => 'bar').
1207    * @param string $keyField
1208    *   Ex: 'key'.
1209    * @param string $valueField
1210    *   Ex: 'value'.
1211    * @return array
1212    * @deprecated
1213    */
1214   public static function toKeyValueRows($array, $keyField = 'key', $valueField = 'value') {
1215     return self::makeNonAssociative($array, $keyField, $valueField);
1216   }
1217
1218   /**
1219    * Convert array where key(s) holds the actual value and value(s) as 1 into array of actual values
1220    *  Ex: array('foobar' => 1, 4 => 1) formatted into array('foobar', 4)
1221    *
1222    * @deprecated use convertCheckboxInputToArray instead (after testing)
1223    * https://github.com/civicrm/civicrm-core/pull/8169
1224    *
1225    * @param array $array
1226    */
1227   public static function formatArrayKeys(&$array) {
1228     if (!is_array($array)) {
1229       return;
1230     }
1231     $keys = array_keys($array, 1);
1232     if (count($keys) > 1 ||
1233       (count($keys) == 1 &&
1234         (current($keys) > 1 ||
1235           is_string(current($keys)) ||
1236           // handle (0 => 4), (1 => 1)
1237           (current($keys) == 1 && $array[1] == 1)
1238         )
1239       )
1240     ) {
1241       $array = $keys;
1242     }
1243   }
1244
1245   /**
1246    * Convert the data format coming in from checkboxes to an array of values.
1247    *
1248    * The input format from check boxes looks like
1249    *   array('value1' => 1, 'value2' => 1). This function converts those values to
1250    *   array(''value1', 'value2).
1251    *
1252    * The function will only alter the array if all values are equal to 1.
1253    *
1254    * @param array $input
1255    *
1256    * @return array
1257    */
1258   public static function convertCheckboxFormatToArray($input) {
1259     if (isset($input[0])) {
1260       return $input;
1261     }
1262     $keys = array_keys($input, 1);
1263     if ((count($keys) == count($input))) {
1264       return $keys;
1265     }
1266     return $input;
1267   }
1268
1269   /**
1270    * Ensure that array is encoded in utf8 format.
1271    *
1272    * @param array $array
1273    *
1274    * @return array $array utf8-encoded.
1275    */
1276   public static function encode_items($array) {
1277     foreach ($array as $key => $value) {
1278       if (is_array($value)) {
1279         $array[$key] = self::encode_items($value);
1280       }
1281       elseif (is_string($value)) {
1282         $array[$key] = mb_convert_encoding($value, mb_detect_encoding($value, mb_detect_order(), TRUE), 'UTF-8');
1283       }
1284       else {
1285         $array[$key] = $value;
1286       }
1287     }
1288     return $array;
1289   }
1290
1291   /**
1292    * Build tree of elements.
1293    *
1294    * @param array $elements
1295    * @param int|null $parentId
1296    *
1297    * @return array
1298    */
1299   public static function buildTree($elements, $parentId = NULL) {
1300     $branch = [];
1301
1302     foreach ($elements as $element) {
1303       if ($element['parent_id'] == $parentId) {
1304         $children = self::buildTree($elements, $element['id']);
1305         if ($children) {
1306           $element['children'] = $children;
1307         }
1308         $branch[] = $element;
1309       }
1310     }
1311
1312     return $branch;
1313   }
1314
1315   /**
1316    * Find search string in tree.
1317    *
1318    * @param string $search
1319    * @param array $tree
1320    * @param string $field
1321    *
1322    * @return array|null
1323    */
1324   public static function findInTree($search, $tree, $field = 'id') {
1325     foreach ($tree as $item) {
1326       if ($item[$field] == $search) {
1327         return $item;
1328       }
1329       if (!empty($item['children'])) {
1330         $found = self::findInTree($search, $item['children']);
1331         if ($found) {
1332           return $found;
1333         }
1334       }
1335     }
1336     return NULL;
1337   }
1338
1339   /**
1340    * Prepend string prefix to every key in an array
1341    *
1342    * @param array $collection
1343    * @param string $prefix
1344    * @return array
1345    */
1346   public static function prefixKeys(array $collection, string $prefix) {
1347     $result = [];
1348     foreach ($collection as $key => $value) {
1349       $result[$prefix . $key] = $value;
1350     }
1351     return $result;
1352   }
1353
1354 }