[9.x] Introduce annotated builder contracts (#40546)

* Introduce annotated builder contracts

* Add tests from previous branch

* StyleCI

* Update Builder.php

* Update Builder.php

Co-authored-by: Taylor Otwell <[email protected]>

Author: inxilpro

src/Illuminate/Contracts/Database/Eloquent/Builder.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace Illuminate\Contracts\Database\Eloquent;
+
+use Illuminate\Contracts\Database\Query\Builder as BaseContract;
+
+/**
+ * This interface is intentionally empty and exists to improve IDE support.
+ *
+ * @mixin \Illuminate\Database\Eloquent\Builder
+ */
+interface Builder extends BaseContract
+{
+}

src/Illuminate/Contracts/Database/Query/Builder.php

@@ -0,0 +1,12 @@
+<?php
+
+namespace Illuminate\Contracts\Database\Query;
+
+/**
+ * This interface is intentionally empty and exists to improve IDE support.
+ *
+ * @mixin \Illuminate\Database\Query\Builder
+ */
+interface Builder
+{
+}

src/Illuminate/Database/Eloquent/Builder.php

@@ -5,6 +5,7 @@
 use BadMethodCallException;
 use Closure;
 use Exception;
+use Illuminate\Contracts\Database\Eloquent\Builder as BuilderContract;
 use Illuminate\Contracts\Support\Arrayable;
 use Illuminate\Database\Concerns\BuildsQueries;
 use Illuminate\Database\Eloquent\Concerns\QueriesRelationships;
@@ -24,7 +25,7 @@
  *
  * @mixin \Illuminate\Database\Query\Builder
  */
-class Builder
+class Builder implements BuilderContract
 {
     use BuildsQueries, ForwardsCalls, QueriesRelationships {
         BuildsQueries::sole as baseSole;

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

@@ -3,6 +3,7 @@
 namespace Illuminate\Database\Eloquent\Relations;
 
 use Closure;
+use Illuminate\Contracts\Database\Eloquent\Builder as BuilderContract;
 use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Database\Eloquent\Collection;
 use Illuminate\Database\Eloquent\Model;
@@ -13,7 +14,7 @@
 use Illuminate\Support\Traits\ForwardsCalls;
 use Illuminate\Support\Traits\Macroable;
 
-abstract class Relation
+abstract class Relation implements BuilderContract
 {
     use ForwardsCalls, Macroable {
         Macroable::__call as macroCall;

src/Illuminate/Database/Query/Builder.php

@@ -6,6 +6,7 @@
 use Carbon\CarbonPeriod;
 use Closure;
 use DateTimeInterface;
+use Illuminate\Contracts\Database\Query\Builder as BuilderContract;
 use Illuminate\Contracts\Support\Arrayable;
 use Illuminate\Database\Concerns\BuildsQueries;
 use Illuminate\Database\Concerns\ExplainsQueries;
@@ -25,7 +26,7 @@
 use LogicException;
 use RuntimeException;
 
-class Builder
+class Builder implements BuilderContract
 {
     use BuildsQueries, ExplainsQueries, ForwardsCalls, Macroable {
         __call as macroCall;

tests/Database/DatabaseEloquentSoftDeletesIntegrationTest.php

@@ -52,6 +52,7 @@ public function createSchema()
             $table->increments('id');
             $table->integer('user_id');
             $table->string('title');
+            $table->integer('priority')->default(0);
             $table->timestamps();
             $table->softDeletes();
         });
@@ -491,6 +492,109 @@ public function testHasManyRelationshipCanBeSoftDeleted()
         $this->assertCount(1, $abigail->posts()->withTrashed()->get());
     }
 
+    public function testRelationToSqlAppliesSoftDelete()
+    {
+        $this->createUsers();
+
+        $abigail = SoftDeletesTestUser::where('email', '[email protected]')->first();
+
+        $this->assertSame(
+            'select * from "posts" where "posts"."user_id" = ? and "posts"."user_id" is not null and "posts"."deleted_at" is null',
+            $abigail->posts()->toSql()
+        );
+    }
+
+    public function testRelationExistsAndDoesntExistHonorsSoftDelete()
+    {
+        $this->createUsers();
+        $abigail = SoftDeletesTestUser::where('email', '[email protected]')->first();
+
+        // 'exists' should return true before soft delete
+        $abigail->posts()->create(['title' => 'First Title']);
+        $this->assertTrue($abigail->posts()->exists());
+        $this->assertFalse($abigail->posts()->doesntExist());
+
+        // 'exists' should return false after soft delete
+        $abigail->posts()->first()->delete();
+        $this->assertFalse($abigail->posts()->exists());
+        $this->assertTrue($abigail->posts()->doesntExist());
+
+        // 'exists' should return true after restore
+        $abigail->posts()->withTrashed()->restore();
+        $this->assertTrue($abigail->posts()->exists());
+        $this->assertFalse($abigail->posts()->doesntExist());
+
+        // 'exists' should return false after a force delete
+        $abigail->posts()->first()->forceDelete();
+        $this->assertFalse($abigail->posts()->exists());
+        $this->assertTrue($abigail->posts()->doesntExist());
+    }
+
+    public function testRelationCountHonorsSoftDelete()
+    {
+        $this->createUsers();
+        $abigail = SoftDeletesTestUser::where('email', '[email protected]')->first();
+
+        // check count before soft delete
+        $abigail->posts()->create(['title' => 'First Title']);
+        $abigail->posts()->create(['title' => 'Second Title']);
+        $this->assertEquals(2, $abigail->posts()->count());
+
+        // check count after soft delete
+        $abigail->posts()->where('title', 'Second Title')->delete();
+        $this->assertEquals(1, $abigail->posts()->count());
+
+        // check count after restore
+        $abigail->posts()->withTrashed()->restore();
+        $this->assertEquals(2, $abigail->posts()->count());
+
+        // check count after a force delete
+        $abigail->posts()->where('title', 'Second Title')->forceDelete();
+        $this->assertEquals(1, $abigail->posts()->count());
+    }
+
+    public function testRelationAggregatesHonorsSoftDelete()
+    {
+        $this->createUsers();
+        $abigail = SoftDeletesTestUser::where('email', '[email protected]')->first();
+
+        // check aggregates before soft delete
+        $abigail->posts()->create(['title' => 'First Title', 'priority' => 2]);
+        $abigail->posts()->create(['title' => 'Second Title', 'priority' => 4]);
+        $abigail->posts()->create(['title' => 'Third Title', 'priority' => 6]);
+        $this->assertEquals(2, $abigail->posts()->min('priority'));
+        $this->assertEquals(6, $abigail->posts()->max('priority'));
+        $this->assertEquals(12, $abigail->posts()->sum('priority'));
+        $this->assertEquals(4, $abigail->posts()->avg('priority'));
+
+        // check aggregates after soft delete
+        $abigail->posts()->where('title', 'First Title')->delete();
+        $this->assertEquals(4, $abigail->posts()->min('priority'));
+        $this->assertEquals(6, $abigail->posts()->max('priority'));
+        $this->assertEquals(10, $abigail->posts()->sum('priority'));
+        $this->assertEquals(5, $abigail->posts()->avg('priority'));
+
+        // check aggregates after restore
+        $abigail->posts()->withTrashed()->restore();
+        $this->assertEquals(2, $abigail->posts()->min('priority'));
+        $this->assertEquals(6, $abigail->posts()->max('priority'));
+        $this->assertEquals(12, $abigail->posts()->sum('priority'));
+        $this->assertEquals(4, $abigail->posts()->avg('priority'));
+
+        // check aggregates after a force delete
+        $abigail->posts()->where('title', 'Third Title')->forceDelete();
+        $this->assertEquals(2, $abigail->posts()->min('priority'));
+        $this->assertEquals(4, $abigail->posts()->max('priority'));
+        $this->assertEquals(6, $abigail->posts()->sum('priority'));
+        $this->assertEquals(3, $abigail->posts()->avg('priority'));
+    }
+
+    public function testSoftDeleteIsAppliedToNewQuery()
+    {
+        $query = (new SoftDeletesTestUser)->newQuery();
+        $this->assertSame('select * from "users" where "users"."deleted_at" is null', $query->toSql());
+    }
+
     public function testSecondLevelRelationshipCanBeSoftDeleted()
     {
         $this->createUsers();