[8.x] Make sole() relationship friendly

src/Illuminate/Database/Eloquent/Relations/Relation.php

@@ -6,6 +6,8 @@
 use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Database\Eloquent\Collection;
 use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\ModelNotFoundException;
+use Illuminate\Database\MultipleRecordsFoundException;
 use Illuminate\Database\Query\Expression;
 use Illuminate\Support\Arr;
 use Illuminate\Support\Traits\ForwardsCalls;
@@ -151,6 +153,30 @@ public function getEager()
         return $this->get();
     }
 
+    /**
+     * Execute the query and get the first result if it's the sole matching record.
+     *
+     * @param  array|string  $columns
+     * @return \Illuminate\Database\Eloquent\Model
+     *
+     * @throws \Illuminate\Database\Eloquent\ModelNotFoundException
+     * @throws \Illuminate\Database\MultipleRecordsFoundException
+     */
+    public function sole($columns = ['*'])
+    {
+        $result = $this->take(2)->get($columns);
+
+        if ($result->isEmpty()) {
+            throw (new ModelNotFoundException)->setModel(get_class($this->model));
+        }
+
+        if ($result->count() > 1) {
+            throw new MultipleRecordsFoundException;
+        }
+
+        return $result->first();
+    }
+
     /**
      * Execute the query as a "select" statement.
      *

tests/Database/DatabaseEloquentIntegrationTest.php

@@ -805,6 +805,20 @@ public function testHasOnMorphToRelationship()
         $this->assertEquals(1, $photos->count());
     }
 
+    public function testBelongsToManyRelationshipModelsAreProperlyHydratedWithSoleQuery()
+    {
+        $user = EloquentTestUserWithCustomFriendPivot::create(['email' => 'taylorotwell@gmail.com']);
+        $user->friends()->create(['email' => 'abigailotwell@gmail.com']);
+
+        $user->friends()->get()->each(function ($friend) {
+            $this->assertTrue($friend->pivot instanceof EloquentTestFriendPivot);
+        });
+
+        $soleFriend = $user->friends()->where('email', 'abigailotwell@gmail.com')->sole();
+
+        $this->assertTrue($soleFriend->pivot instanceof EloquentTestFriendPivot);
+    }
+
     public function testBelongsToManyRelationshipModelsAreProperlyHydratedOverChunkedRequest()
     {
         $user = EloquentTestUser::create(['email' => 'taylorotwell@gmail.com']);