Added find method

Author: minwork

README.md

@@ -34,7 +34,15 @@ Advanced implementation of well known operations:
 ## Example of usage
 ```php
 // Set nested array value
-$array = Arr::set([], 'key1.key2.key3', 'my_value');
+$array = Arr::set([], 'key1.key2.key3', 'my_value'); 
+// Which is equivalent to
+[
+  'key1' => [
+    'key2' => [
+      'key3' => 'my_value'
+    ]
+  ]
+]
 
 // Get nested array value
 Arr::get($array, 'key1.key2') -> ['key3' => 'my_value']
@@ -47,6 +55,11 @@ Arr::map($array, function ($key, $value) {
    // Your code here
 });
 
+// Find array element
+Arr::find($array, function ($element) {
+  return Arr::get($element, 'key2.key3') === 'my_value';
+}) -> [ 'key2' => [ 'key3' => 'my_value'] ]
+
 // Chain few methods
 Arr::obj(['test' => 1, 'foo' => 'bar'])
     ->set('abc', 123)

src/Arr.php

@@ -10,6 +10,8 @@
 
 use ArrayAccess;
 use InvalidArgumentException;
+use Iterator;
+use IteratorAggregate;
 use ReflectionFunction;
 use ReflectionMethod;
 use Throwable;
@@ -59,6 +61,19 @@ class Arr
      */
     const UNPACK_PRESERVE_ARRAY = 8;
 
+    /**
+     * Return value of array element matching find condition
+     */
+    const FIND_RETURN_VALUE = 'value';
+    /**
+     * Return key of array element matching find condition
+     */
+    const FIND_RETURN_KEY = 'key';
+    /**
+     * Return all values (preserving original keys) of array elements matching find condition
+     */
+    const FIND_RETURN_ALL = 'all';
+
     private const AUTO_INDEX_KEY = '[]';
     private const KEY_SEPARATOR = '.';
 
@@ -112,7 +127,7 @@ public static function has(array $array, $keys): bool
 
         foreach ($keysArray as $key) {
             if (!array_key_exists($key, $tmp)) {
-                 return false;
+                return false;
             }
             $tmp = $tmp[$key];
         }
@@ -692,6 +707,34 @@ public static function groupObjects(array $objects, string $method, ...$args): a
         return $return;
     }
 
+    /**
+     * Find array (or iterable object) element(s) that match specified condition
+     *
+     * @param array|Iterator|IteratorAggregate $array
+     * @param callable $condition Callable accepting one argument (current array element value) and returning truthy or falsy value
+     * @param string $return What type of result should be returned after finding desired element(s)
+     * @return mixed|mixed[] Either key, value or assoc array containing keys and values for elements matching specified condition. Returns null if element was not found, or empty array if FIND_RETURN_ALL mode was used.
+     */
+    public static function find($array, callable $condition, string $return = self::FIND_RETURN_VALUE)
+    {
+        $result = [];
+        foreach ($array as $key => $value) {
+            if (call_user_func($condition, $value)) {
+                switch ($return) {
+                    case self::FIND_RETURN_KEY:
+                        return $key;
+                    case self::FIND_RETURN_VALUE:
+                        return $value;
+                    case self::FIND_RETURN_ALL:
+                        $result[$key] = $value;
+                        break;
+                }
+            }
+        }
+
+        return $return === self::FIND_RETURN_ALL ? $result : null;
+    }
+
     /**
      * Order associative array according to supplied keys order
      * Keys that are not present in $keys param will be appended to the end of an array preserving supplied order.
@@ -977,7 +1020,7 @@ public static function getDepth(array $array): int
                     }
                 }
             }
-        } while(!empty($queue));
+        } while (!empty($queue));
 
         return $depth;
     }

src/ArrObj.php

@@ -6,6 +6,7 @@
 use ArrayIterator;
 use BadMethodCallException;
 use Countable;
+use Iterator;
 use IteratorAggregate;
 
 /**
@@ -78,6 +79,11 @@
  *
  * ---------------------------------------------------------------------------------
  *
+ * @method ArrObj find(array|IteratorAggregate|Iterator $array, callable $condition, string $return)
+ * @see Arr::find()
+ *
+ * ---------------------------------------------------------------------------------
+ *
  * @method ArrObj orderByKeys(mixed $keys, bool $appendUnmatched = true)
  * @see Arr::orderByKeys()
  *
@@ -166,6 +172,7 @@ class ArrObj implements IteratorAggregate, ArrayAccess, Countable
         'filterObjects',
         'group',
         'groupObjects',
+        'find',
         'orderByKeys',
         'sortByKeys',
         'sortObjects',

test/Arr/ArrTest.php

@@ -90,7 +90,6 @@ public function testGetNestedElement($class)
         $this->assertSame(['test'], $this->callMethod([$class, 'get'], $array, 'key1.key2.key3'));
         $this->assertSame('test', $this->callMethod([$class, 'get'], $array, 'key1.key2.key3.0'));
         $this->assertSame('default', $this->callMethod([$class, 'get'], $array, 'key1.key4.key2.key3', 'default'));
-        /** @noinspection PhpParamsInspection */
         $this->assertSame('default', $this->callMethod([$class, 'get'], new stdClass(), 'key1.key4.key2.key3', 'default'));
         $this->assertNull($this->callMethod([$class, 'get'], $array, 'key1.key4.key2.key3'));
 
@@ -823,6 +822,52 @@ public function testGroupObjects($class)
         ], $this->callMethod([$class, 'groupObjects'], ['a', 'b', 'c', $object3], 'test'));
     }
 
+    /**
+     * @param array $array
+     * @dataProvider arrayProvider
+     */
+    public function testFind($array)
+    {
+        $elCount = count($array);
+        $randomElement = Arr::random($array);
+        $randomElementKey = array_search($randomElement, $array, true);
+        $randomElements = $elCount === 1 ? [$randomElementKey => $randomElement] : Arr::random($array, min(3, $elCount));
+        $callbackSingle = function ($value) use ($randomElement) {
+            return $value === $randomElement;
+        };
+        $callbackAll = function ($value) use ($randomElements) {
+            return in_array($value, $randomElements, true);
+        };
+        $callbackNotFound = function () {
+            return false;
+        };
+
+        // Default (value)
+        $this->assertSame($randomElement, Arr::find($array, $callbackSingle));
+
+        // Return value
+        $this->assertSame($randomElement, Arr::find($array, $callbackSingle, Arr::FIND_RETURN_VALUE));
+
+        // Return key
+        $this->assertSame($randomElementKey, Arr::find($array, $callbackSingle, Arr::FIND_RETURN_KEY));
+
+        // Return all
+        $this->assertSame($randomElements, Arr::find($array, $callbackAll, Arr::FIND_RETURN_ALL), "Elements " . print_r($randomElements, true));
+
+        // Not found (default - value)
+        $this->assertSame(null, Arr::find($array, $callbackNotFound));
+
+        // Not found (value)
+        $this->assertSame(null, Arr::find($array, $callbackNotFound, Arr::FIND_RETURN_VALUE));
+
+        // Not found (key)
+        $this->assertSame(null, Arr::find($array, $callbackNotFound, Arr::FIND_RETURN_KEY));
+
+        // Not found (all)
+        $this->assertSame([], Arr::find($array, $callbackNotFound, Arr::FIND_RETURN_ALL));
+
+    }
+
     /**
      * @param $class string|ArrObj
      *

test/ArrTestCase.php

@@ -16,6 +16,7 @@ class ArrTestCase extends TestCase
         'bool' => true,
         'float' => 1.0,
         'null' => null,
+        'callable' => 'boolval',
     ];
 
     /**