Iterator Utility

Helpers for iterate and handle throught lists.

class IteratorUtility

Fully qualified name: \Jar\Utilities\Utilities\IteratorUtility

sortArrayByColumn ( &$arr, $col, $dir = SORT_ASC)

Sort array by column/key value.

param array $arr: Reference of array.
param string $col: The column/key name.
param int $dir: The direction SORT_ASC or SORT_DESC

Example:

$persons = [
   [
      'name' => 'peter',
      'age' => 34
   ],
   [
      'name' => 'klaus',
      'age' => 21
   ],
   [
      'name' => 'michael',
      'age' => 17
   ],
];

IteratorUtility::sortArrayByColumn($persons, 'age');

returns

[
   [
      'name' =>  'michael' 
      'age' =>  17
   ],
   [
      'name' =>  'klaus' 
      'age' =>  21
   ],
   [
      'name' =>  'peter' 
      'age' =>  34
   ]
]

extractValuesViaGetMethod ( $listOfObjects, $methodName)

Extracts properties from objects via their get method.

param array $listOfObjects: List of objects.
param string $methodName: The name of the method, without the beginning 'get'.

Example:

class Person
{
   private string $name;

   function __construct($name)
   {
      $this->name = $name;
   }

   public function getName(): string
   {
      return $this->name;
   }
};

/* ... */


$persons = [ new Person('klaus'), new Person('peter')];
$names = IteratorUtility::extractValuesViaGetMethod($persons, 'name');

var_dump($names);

returns

['klaus', 'peter']

Returns: Extracted values.

extractValuesViaGetMethodFlattened ( $listOfObjects, $methodName, $keepKeys = false)

Extracts properties from objects via their get method and flattens the result.

param array $listOfObjects: List of objects.
param string $methodName: The name of the method, without the beginning 'get'.
param bool $keepKeys: Keep keys in result. Will overwrite existing values for this key.

Example:

class Element
{
   private array $items;

   function __construct($items)
   {
      $this->items = $items;
   }

   public function getItems(): array
   {
      return $this->items;
   }
};

/* ... */


$elements = [
   new Element(
      [
         'a' => 1,
         'b' => 2,
         'c' => 3,
         'd' => 4
      ]
   ),
   new Element([
      'e' => 5,
      'f' => 6,
      'g' => 7,
      'a' => 8
   ])
];

// without "keepKeys"

$allItems = IteratorUtility::extractValuesViaGetMethodFlattened($elements, 'items');      
var_dump($allItems);
/*
   Result:
      0 =>  1
      1 =>  2
      2 =>  3
      3 =>  4
      4 =>  5
      5 =>  6
      6 =>  7
      7 =>  8
*/

// with "keepKeys"

$allItems = IteratorUtility::extractValuesViaGetMethodFlattened($elements, 'items', true);
var_dump($allItems);
/*
   Result:
      'a' =>  8
      'b' =>  2
      'c' =>  3
      'd' =>  4
      'e' =>  5
      'f' =>  6
      'g' =>  7
*/

Returns: Extracted flattened values.

callMethod ( $listOfObjects, $method)

Calls a method in each object and returns the results.

param array $listOfObjects: List of objects.
param string $method: name of the method.

Example:

class Element
{
   private int $number;

   function __construct($number)
   {
      $this->number = $number;
   }

   public function add(): int
   {
      return $this->number + 1;
   }
};

/* ... */

$numbers = [ new Element(5), new Element(2) ];

$addedNumbers = IteratorUtility::callMethod($numbers, 'add');

var_dump($addedNumbers);

returns

[6, 3]

Returns: List of method results.

compact ( $arr)

Returns a copy of the list with all falsy values (null, 0, '') removed.

param array $arr: List with values.

Example:

IteratorUtility::compact(['hello', null, '', 0, 'world'])

returns

['hello', 'world']

Returns: List without falsy values

flatten ( $arr)

Flattens a nested array.

param array $arr: The nested array.

Example:

IteratorUtility::flatten([
   [1, 2, 3],
   [4, 5],
   [6]
]);

returns

[1, 2, 3, 4, 5, 6]

Returns: The flat array.

filter ( $arr, $func)

Filters a list with a closure condition

param array $arr: The array.
param callable $func: The filter closure.

Example:

IteratorUtility::filter(
   [1, 2, 3, 4, 5, 6],
   function($value) {            
      return (bool) ($value % 2);
   }
);

returns

[1, 3, 5]

Returns: The filtered result.

map ( $arr, $func)

Iterates each item and maps the new value throught a function.

param array $arr

The array.

param callable $func The transformation function (receives three parametes

value, 2. key, 3. current transformated list).

Example:

IteratorUtility::map(
   [1, 2, 3, 4, 5, 6],
   function($value) {            
      return $value * 2;
   }
);

returns

[2, 4, 6, 8, 10, 12]

Returns: The mapped array.

first ( $arr)

Returns the first element from a list.

param array $arr: The array.

Example:

IteratorUtility::first(['hello', 'world'])

returns

'hello'

Returns: First element.

pluck ( $arr, $key)

Extracts a the value of a certain key.

param array $arr: The array.
param string $key: The key.

Example:

$persons = [
   [
      'name' => 'peter',
      'age' => 34
   ],
   [
      'name' => 'klaus',
      'age' => 21
   ],
   [
      'name' => 'michael',
      'age' => 17
   ],
];

IteratorUtility::pluck($persons, 'name');

returns

['peter' , 'klaus' , 'michael']

Returns: The extracted values.

contains ( $arr, $needle)

Checks if a value exist in an array.

param array $arr: The array.
param string $needle: The value to check.

Example:

// true
IteratorUtility::contains([1, 2, 3, 4, 5, 6], 2);

// false
IteratorUtility::contains([1, 2, 3, 4, 5, 6], 7);

Returns: Check result.

whitelist ( $array, $whitelist)

Returns only array entries listed in a whitelist.

param array $array: Original array to operate on.
param array $whitelist: Keys you want to keep.

Example:

IteratorUtility::whitelist([
   'a' => 1,
   'b' => 2,
   'c' => 3,
   'd' => 4
], ['a', 'c']);

returns

[
   'a' =>  1,
   'c' =>  3
]

Returns: The whitelisted entries.

whitelistList ( $array, $whitelist)

Returns only nested array entries listed in a whitelist.

param array $array: List of nested array items
param array $whitelist: Keys you want to keep.

Example:

IteratorUtility::whitelistList([
   [
      'a' => 1,
      'b' => 2,
      'c' => 3,
      'd' => 4
   ],
   [
      'a' => 5,
      'b' => 6,
      'c' => 7,
      'd' => 8
   ]
], ['a', 'c'])

returns

[
   [
      'a' =>  1,
      'c' =>  3
   ],
   [
      'a' =>  5,
      'c' =>  7
   ]
]

Returns: The whitelisted entries.

indexBy ( $arr, $key)

Create a indexed list based on key values.

param array $array: The array.
param string $key: The index key name.

Example:

$persons = [
   [
      'id' => 5,
      'name' => 'peter',
   ],
   [
      'id' => 2,
      'name' => 'klaus',
   ],
   [
      'id' => 3,
      'name' => 'michael',
   ],
];      

var_dump($persons);
/*
   Result: 
   [
      0 => [
         'id' =>  5
         'name' =>  'peter'
      ],
      1 => [
         'id' =>  2
         'name' =>  'klaus'
      ],
      2 => [
         'id' =>  3
         'name' =>  'michael'
      ]
   ]
*/

$indexedPersons = IteratorUtility::indexBy($persons, 'id');

var_dump($indexedPersons);
/*
   Result: 
   [
      5 => [
         'id' =>  5
         'name' =>  'peter'
      ],
      2 => [
         'id' =>  2
         'name' =>  'klaus'
      ],
      3 => [
         'id' =>  3
         'name' =>  'michael'
      ]
   ]
*/

Returns: The indexed List.