[12.x] Add Arr::soleValue method

src/Illuminate/Collections/Arr.php

@@ -841,6 +841,25 @@ public static function sole($array, ?callable $callback = null)
         return static::first($array);
     }
 
+    /**
+     * Get a single value from the first element matching the given callback or from the only element in the array.
+     *
+     * @template TKey
+     * @template TValue
+     *
+     * @param  iterable<TKey, TValue>  $array
+     * @param  string|int|callable  $key
+     * @param  callable|null  $callback
+     * @return mixed
+     *
+     * @throws \Illuminate\Support\ItemNotFoundException
+     * @throws \Illuminate\Support\MultipleItemsFoundException
+     */
+    public static function soleValue($array, $key, ?callable $callback = null)
+    {
+        return static::get(static::sole($array, $callback), $key);
+    }
+
     /**
      * Sort the array using the given callback or "dot" notation.
      *

tests/Support/SupportArrTest.php

@@ -1098,6 +1098,41 @@ public function testSoleThrowsExceptionIfMoreThanOneItemExists()
         Arr::sole(['baz', 'foo', 'baz'], fn (string $value) => $value === 'baz');
     }
 
+    public function testSoleValueReturnsValueFromSingleElement()
+    {
+        $array = [
+            ['name' => 'foo', 'age' => 25],
+        ];
+
+        $this->assertSame('foo', Arr::soleValue($array, 'name'));
+        $this->assertSame(25, Arr::soleValue($array, 'age'));
+    }
+
+    public function testSoleValueReturnsValueFromCallbackFilteredElement()
+    {
+        $array = [
+            ['name' => 'foo', 'age' => 25],
+            ['name' => 'bar', 'age' => 30],
+        ];
+
+        $this->assertSame('foo', Arr::soleValue($array, 'name', fn (array $value) => $value['age'] === 25));
+        $this->assertSame(30, Arr::soleValue($array, 'age', fn (array $value) => $value['name'] === 'bar'));
+    }
+
+    public function testSoleValueThrowsExceptionIfNoItemsExist()
+    {
+        $this->expectException(ItemNotFoundException::class);
+
+        Arr::soleValue([], 'id');
+    }
+
+    public function testSoleValueThrowsExceptionIfMoreThanOneItemExists()
+    {
+        $this->expectExceptionObject(new MultipleItemsFoundException(2));
+
+        Arr::soleValue([['id' => 1], ['id' => 2]], 'id');
+    }
+
     public function testEmptyShuffle()
     {
         $this->assertEquals([], Arr::shuffle([]));