feat(repository): optionally opt-out of eager-loading

API-1184

src/Abstracts/Repositories/Repository.php

@@ -18,20 +18,31 @@ abstract class Repository extends BaseRepository implements CacheableInterface
     }
 
     // TODO: BC: set return type to void
+    /**
+     * Define the maximum number of entries per page that is returned.
+     * Set to 0 to "disable" this feature.
+     */
+    protected int $maxPaginationLimit = 0;
+
+    protected bool|null $allowDisablePagination = null;
+
     public function boot()
     {
         parent::boot();
 
-        $this->eagerLoadRequestedRelations();
+        if ($this->includesEagerLoadingEnabled()) {
+            $this->eagerLoadRequestedRelations();
+        }
     }
 
     /**
-     * Define the maximum number of entries per page that is returned.
-     * Set to 0 to "disable" this feature.
+     * Enable or disable eager loading of relations requested by the client via "include" query parameter.
      */
-    protected int $maxPaginationLimit = 0;
-
-    protected bool|null $allowDisablePagination = null;
+    public function includesEagerLoadingEnabled(): bool
+    {
+        // TODO: BC: disable it by default for v8 and enable by default for v13
+        return false;
+    }
 
     /**
      * This function relies on strict conventions:

tests/Unit/Abstracts/Repositories/RepositoryTest.php

@@ -61,17 +61,23 @@ public static function includeDataProvider(): array
     #[DataProvider('includeDataProvider')]
     public function testEagerLoadSingleRelationRequestedViaRequest(
         string $include,
-        array $userMustLoadRelations,
-        array $booksMustLoadRelations,
-        array $mustNotLoadRelations,
+        array  $userMustLoadRelations,
+        array  $booksMustLoadRelations,
+        array  $mustNotLoadRelations,
     ): void {
         request()->merge(compact('include'));
         UserFactory::new()
-            ->has(UserFactory::new()->has(BookFactory::new())->count(3), 'children')
-            ->has(BookFactory::new())->count(3)
+            ->has(UserFactory::new()
+                ->has(BookFactory::new()->count(3)),
+                'children',
+            )->has(BookFactory::new()->count(3))
             ->createOne();
-
-        $repository = app(UserRepository::class);
+        $repository = new class(app()) extends UserRepository {
+            public function includesEagerLoadingEnabled(): bool
+            {
+                return true;
+            }
+        };
 
         $result = $repository->all();
 
@@ -92,16 +98,28 @@ public function testEagerLoadSingleRelationRequestedViaRequest(
 
     public function testMultipleEagerLoadAppliesAllEagerLoads(): void
     {
-        $parent = UserFactory::new()->createOne();
-        UserFactory::new()->count(3)->create(['parent_id' => $parent->id]);
-        $repository = app(UserRepository::class);
+        UserFactory::new()
+            ->has(UserFactory::new()
+                ->has(BookFactory::new()->count(3)),
+                'children',
+            )->has(BookFactory::new()->count(3))
+            ->createOne();
+        $repository = new class(app()) extends UserRepository {
+            public function includesEagerLoadingEnabled(): bool
+            {
+                return true;
+            }
+        };
 
         /** @var Collection<int, User> $result */
-        $result = $repository->with('parent')->with('children')->all();
+        $result = $repository->with('books')->with('children.books')->all();
 
         $result->each(function (User $user) {
-            $this->assertTrue($user->relationLoaded('parent'));
+            $this->assertTrue($user->relationLoaded('books'));
             $this->assertTrue($user->relationLoaded('children'));
+            foreach ($user->children as $child) {
+                $this->assertTrue($child->relationLoaded('books'));
+            }
         });
     }