Merge branch 'master' into 3.2-merge

Author: limingxinleo

src/Arr.php

@@ -598,6 +598,27 @@ public static function shuffleAssoc(array $array, ?int $seed = null): array
         return $random;
     }
 
+    /**
+     * Get the first item in the collection, but only if exactly one item exists. Otherwise, throw an exception.
+     *
+     * @param array $array
+     *
+     * @throws ItemNotFoundException
+     * @throws MultipleItemsFoundException
+     */
+    public static function sole($array, ?callable $callback = null)
+    {
+        if ($callback) {
+            $array = static::where($array, $callback);
+        }
+
+        return match (count($array)) {
+            0 => throw new ItemNotFoundException(),
+            1 => static::first($array),
+            default => throw new MultipleItemsFoundException(count($array)),
+        };
+    }
+
     /**
      * Sort the array using the given callback or "dot" notation.
      */

tests/ArrTest.php

@@ -15,6 +15,8 @@
 use ArrayObject;
 use Hyperf\Collection\Arr;
 use Hyperf\Collection\Collection;
+use Hyperf\Collection\ItemNotFoundException;
+use Hyperf\Collection\MultipleItemsFoundException;
 use Hyperf\Coroutine\Coroutine;
 use Hyperf\Di\Resolver\ResolverDispatcher;
 use InvalidArgumentException;
@@ -1058,4 +1060,33 @@ public function testPush(): void
         $array = ['foo' => ['bar' => false]];
         Arr::push($array, 'foo.bar', 'baz');
     }
+
+    public function testSoleReturnsFirstItemInCollectionIfOnlyOneExists()
+    {
+        $this->assertSame('foo', Arr::sole(['foo']));
+
+        $array = [
+            ['name' => 'foo'],
+            ['name' => 'bar'],
+        ];
+
+        $this->assertSame(
+            ['name' => 'foo'],
+            Arr::sole($array, fn (array $value) => $value['name'] === 'foo')
+        );
+    }
+
+    public function testSoleThrowsExceptionIfNoItemsExist()
+    {
+        $this->expectException(ItemNotFoundException::class);
+
+        Arr::sole(['foo'], fn (string $value) => $value === 'baz');
+    }
+
+    public function testSoleThrowsExceptionIfMoreThanOneItemExists()
+    {
+        $this->expectExceptionObject(new MultipleItemsFoundException(2));
+
+        Arr::sole(['baz', 'foo', 'baz'], fn (string $value) => $value === 'baz');
+    }
 }