[8.x] Added sole() and soleWhere() methods for Collections

src/Illuminate/Collections/Collection.php

@@ -4,6 +4,8 @@
 
 use ArrayAccess;
 use ArrayIterator;
+use Illuminate\Collections\ItemNotFoundException;
+use Illuminate\Collections\MultipleItemsFoundException;
 use Illuminate\Support\Traits\EnumeratesValues;
 use Illuminate\Support\Traits\Macroable;
 use stdClass;
@@ -1050,6 +1052,31 @@ public function splitIn($numberOfGroups)
         return $this->chunk(ceil($this->count() / $numberOfGroups));
     }
 
+    /**
+     * Get the first item in the collection, but only if exactly
+     * item exists. Otherwise, throw an exception.
+     *
+     * @param  callable|null  $callback
+     * @return mixed
+     *
+     * @throws ItemNotFoundException
+     * @throws MultipleItemsFoundException
+     */
+    public function sole(callable $callback = null)
+    {
+        $items = $this->filter($callback);
+
+        if ($items->isEmpty()) {
+            throw new ItemNotFoundException;
+        }
+
+        if ($items->count() > 1) {
+            throw new MultipleItemsFoundException;
+        }
+
+        return $items->first();
+    }
+
     /**
      * Chunk the collection into chunks of the given size.
      *

src/Illuminate/Collections/Enumerable.php

@@ -3,6 +3,8 @@
 namespace Illuminate\Support;
 
 use Countable;
+use Illuminate\Collections\ItemNotFoundException;
+use Illuminate\Collections\MultipleItemsFoundException;
 use Illuminate\Contracts\Support\Arrayable;
 use Illuminate\Contracts\Support\Jsonable;
 use IteratorAggregate;
@@ -808,6 +810,30 @@ public function slice($offset, $length = null);
      */
     public function split($numberOfGroups);
 
+    /**
+     * Get the first item in the collection, but only if exactly
+     * item exists. Otherwise, throw an exception.
+     *
+     * @param  callable|null  $callback
+     * @return mixed
+     *
+     * @throws ItemNotFoundException
+     * @throws MultipleItemsFoundException
+     */
+    public function sole(callable $callback = null);
+
+    /**
+     * Get the first item by the given key value pair, but only if
+     * exactly one item matches the criteria. Otherwise, throw
+     * an exception.
+     *
+     * @param  string  $key
+     * @param  mixed  $operator
+     * @param  mixed  $value
+     * @return mixed
+     */
+    public function soleWhere($key, $operator = null, $value = null);
+
     /**
      * Chunk the collection into chunks of the given size.
      *

src/Illuminate/Collections/ItemNotFoundException.php

@@ -0,0 +1,9 @@
+<?php
+
+namespace Illuminate\Collections;
+
+use RuntimeException;
+
+class ItemNotFoundException extends RuntimeException
+{
+}

src/Illuminate/Collections/LazyCollection.php

@@ -5,6 +5,8 @@
 use ArrayIterator;
 use Closure;
 use DateTimeInterface;
+use Illuminate\Collections\ItemNotFoundException;
+use Illuminate\Collections\MultipleItemsFoundException;
 use Illuminate\Support\Traits\EnumeratesValues;
 use Illuminate\Support\Traits\Macroable;
 use IteratorAggregate;
@@ -1010,6 +1012,51 @@ public function split($numberOfGroups)
         return $this->passthru('split', func_get_args());
     }
 
+    /**
+     * Get the first item in the collection, but only if exactly
+     * item exists. Otherwise, throw an exception.
+     *
+     * @param  callable|null  $callback
+     * @return mixed
+     *
+     * @throws ItemNotFoundException
+     * @throws MultipleItemsFoundException
+     */
+    public function sole(callable $callback = null)
+    {
+        $iterator = $this->getIterator();
+
+        if (is_null($callback)) {
+            if (! $iterator->valid()) {
+                throw new ItemNotFoundException;
+            }
+
+            if ($this->take(2)->count() > 1) {
+                throw new MultipleItemsFoundException;
+            }
+
+            return $iterator->current();
+        }
+
+        $items = [];
+
+        foreach ($iterator as $key => $value) {
+            if ($callback($value, $key)) {
+                $items[] = $value;
+            }
+        }
+
+        if (! count($items)) {
+            throw new ItemNotFoundException;
+        }
+
+        if (count($items) > 1) {
+            throw new MultipleItemsFoundException;
+        }
+
+        return $items[0];
+    }
+
     /**
      * Chunk the collection into chunks of the given size.
      *

src/Illuminate/Collections/MultipleItemsFoundException.php

@@ -0,0 +1,9 @@
+<?php
+
+namespace Illuminate\Collections;
+
+use RuntimeException;
+
+class MultipleItemsFoundException extends RuntimeException
+{
+}

src/Illuminate/Collections/Traits/EnumeratesValues.php

@@ -453,6 +453,21 @@ public function sum($callback = null)
         }, 0);
     }
 
+    /**
+     * Get the first item by the given key value pair, but only if
+     * exactly one item matches the criteria. Otherwise, throw
+     * an exception.
+     *
+     * @param  string  $key
+     * @param  mixed  $operator
+     * @param  mixed  $value
+     * @return mixed
+     */
+    public function soleWhere($key, $operator = null, $value = null)
+    {
+        return $this->sole($this->operatorForWhere(...func_get_args()));
+    }
+
     /**
      * Apply the callback if the value is truthy.
      *

tests/Support/SupportCollectionTest.php

@@ -7,6 +7,8 @@
 use ArrayObject;
 use CachingIterator;
 use Exception;
+use Illuminate\Collections\ItemNotFoundException;
+use Illuminate\Collections\MultipleItemsFoundException;
 use Illuminate\Contracts\Support\Arrayable;
 use Illuminate\Contracts\Support\Jsonable;
 use Illuminate\Support\Collection;
@@ -66,6 +68,90 @@ public function testFirstWithDefaultAndWithoutCallback($collection)
         $this->assertSame('default', $result);
     }
 
+    /**
+     * @dataProvider collectionClassProvider
+     */
+    public function testSoleReturnsFirstItemInCollectionIfOnlyOneExists($collection)
+    {
+        $collection = new $collection([
+            ['name' => 'foo'],
+            ['name' => 'bar'],
+        ]);
+
+        $this->assertSame(['name' => 'foo'], $collection->where('name', 'foo')->sole());
+    }
+
+    /**
+     * @dataProvider collectionClassProvider
+     */
+    public function testSoleThrowsExceptionIfNoItemsExists($collection)
+    {
+        $this->expectException(ItemNotFoundException::class);
+
+        $collection = new $collection([
+            ['name' => 'foo'],
+            ['name' => 'bar'],
+        ]);
+
+        $collection->where('name', 'INVALID')->sole();
+    }
+
+    /**
+     * @dataProvider collectionClassProvider
+     */
+    public function testSoleThrowsExceptionIfMoreThanOneItemExists($collection)
+    {
+        $this->expectException(MultipleItemsFoundException::class);
+
+        $collection = new $collection([
+            ['name' => 'foo'],
+            ['name' => 'foo'],
+            ['name' => 'bar'],
+        ]);
+
+        $collection->where('name', 'foo')->sole();
+    }
+
+    /**
+     * @dataProvider collectionClassProvider
+     */
+    public function testSoleReturnsFirstItemInCollectionIfOnlyOneExistsWithCallback($collection)
+    {
+        $data = new $collection(['foo', 'bar', 'baz']);
+        $result = $data->sole(function ($value) {
+            return $value === 'bar';
+        });
+        $this->assertSame('bar', $result);
+    }
+
+    /**
+     * @dataProvider collectionClassProvider
+     */
+    public function testSoleThrowsExceptionIfNoItemsExistsWithCallback($collection)
+    {
+        $this->expectException(ItemNotFoundException::class);
+
+        $data = new $collection(['foo', 'bar', 'baz']);
+
+        $data->sole(function ($value) {
+            return $value === 'invalid';
+        });
+    }
+
+    /**
+     * @dataProvider collectionClassProvider
+     */
+    public function testSoleThrowsExceptionIfMoreThanOneItemExistsWithCallback($collection)
+    {
+        $this->expectException(MultipleItemsFoundException::class);
+
+        $data = new $collection(['foo', 'bar', 'bar']);
+
+        $data->sole(function ($value) {
+            return $value === 'bar';
+        });
+    }
+
     /**
      * @dataProvider collectionClassProvider
      */
@@ -82,6 +168,50 @@ public function testFirstWhere($collection)
         $this->assertNull($data->firstWhere('nonexistent', 'key'));
     }
 
+    /**
+     * @dataProvider collectionClassProvider
+     */
+    public function testSoleWhere($collection)
+    {
+        $data = new $collection([
+            ['material' => 'paper', 'type' => 'book'],
+            ['material' => 'rubber', 'type' => 'gasket'],
+        ]);
+
+        $this->assertSame('book', $data->soleWhere('material', 'paper')['type']);
+    }
+
+    /**
+     * @dataProvider collectionClassProvider
+     */
+    public function testSoleWhereThrowsExceptionIfNoItemExists($collection)
+    {
+        $this->expectException(ItemNotFoundException::class);
+
+        $data = new $collection([
+            ['material' => 'paper', 'type' => 'book'],
+            ['material' => 'rubber', 'type' => 'gasket'],
+        ]);
+
+        $data->soleWhere('material', 'invalid');
+    }
+
+    /**
+     * @dataProvider collectionClassProvider
+     */
+    public function testSoleWhereThrowsExceptionIfMultipleItemsExists($collection)
+    {
+        $this->expectException(MultipleItemsFoundException::class);
+
+        $data = new $collection([
+            ['material' => 'paper', 'type' => 'book'],
+            ['material' => 'paper', 'type' => 'letter'],
+            ['material' => 'rubber', 'type' => 'gasket'],
+        ]);
+
+        $data->soleWhere('material', 'paper');
+    }
+
     /**
      * @dataProvider collectionClassProvider
      */