From 54f3d3f0f4109be11bc85230fd82d72b9b1ac8ab Mon Sep 17 00:00:00 2001
From: Jack Sleight <jacksleight@gmail.com>
Date: Thu, 21 Nov 2024 19:54:10 +0000
Subject: [PATCH] [5.x] Add `always_augment_to_query` option (#11086)

Co-authored-by: Jason Varga <jason@pixelfear.com>
---
 config/system.php                | 13 +++++++++++++
 src/Fieldtypes/Assets/Assets.php |  4 +++-
 src/Fieldtypes/Entries.php       |  4 +++-
 src/Fieldtypes/Terms.php         |  4 +++-
 src/Fieldtypes/Users.php         |  6 +++++-
 5 files changed, 27 insertions(+), 4 deletions(-)

diff --git a/config/system.php b/config/system.php
index 95f4c797ff..fc04ee4b02 100644
--- a/config/system.php
+++ b/config/system.php
@@ -168,6 +168,19 @@
 
     'update_references' => true,
 
+    /*
+    |--------------------------------------------------------------------------
+    | Always Augment to Query
+    |--------------------------------------------------------------------------
+    |
+    | By default, Statamic will augment relationship fields with max_items: 1
+    | to the result of a query, for example an Entry instance. Setting this
+    | to true will augment to the query builder instead of the result.
+    |
+    */
+
+    'always_augment_to_query' => false,
+
     /*
     |--------------------------------------------------------------------------
     | Row ID handle
diff --git a/src/Fieldtypes/Assets/Assets.php b/src/Fieldtypes/Assets/Assets.php
index 4aca4bae9e..a58efcfea8 100644
--- a/src/Fieldtypes/Assets/Assets.php
+++ b/src/Fieldtypes/Assets/Assets.php
@@ -265,7 +265,9 @@ public function augment($values)
 
         $query = new OrderedQueryBuilder($query, $ids);
 
-        return $single ? Blink::once($key, fn () => $query->first()) : $query;
+        return $single && ! config('statamic.system.always_augment_to_query', false)
+            ? Blink::once($key, fn () => $query->first())
+            : $query;
     }
 
     public function shallowAugment($values)
diff --git a/src/Fieldtypes/Entries.php b/src/Fieldtypes/Entries.php
index b51f0706ce..29a9b96e78 100644
--- a/src/Fieldtypes/Entries.php
+++ b/src/Fieldtypes/Entries.php
@@ -370,7 +370,9 @@ public function augment($values)
 
         $query = $this->queryBuilder($values);
 
-        return $single ? Blink::once($key, fn () => $query->first()) : $query;
+        return $single && ! config('statamic.system.always_augment_to_query', false)
+            ? Blink::once($key, fn () => $query->first())
+            : $query;
     }
 
     public function shallowAugment($values)
diff --git a/src/Fieldtypes/Terms.php b/src/Fieldtypes/Terms.php
index 440fa33315..c3b7dd1bd0 100644
--- a/src/Fieldtypes/Terms.php
+++ b/src/Fieldtypes/Terms.php
@@ -123,7 +123,9 @@ public function augment($values)
 
         $query = $this->queryBuilder($values);
 
-        return $single ? Blink::once($key, fn () => $query->first()) : $query;
+        return $single && ! config('statamic.system.always_augment_to_query', false)
+            ? Blink::once($key, fn () => $query->first())
+            : $query;
     }
 
     private function queryBuilder($values)
diff --git a/src/Fieldtypes/Users.php b/src/Fieldtypes/Users.php
index b3e9317701..641d7d99f5 100644
--- a/src/Fieldtypes/Users.php
+++ b/src/Fieldtypes/Users.php
@@ -180,11 +180,15 @@ protected function getItemsForPreProcessIndex($values): Collection
 
     public function augment($values)
     {
+        $single = $this->config('max_items') === 1;
+
         $ids = Arr::wrap($values);
 
         $query = (new OrderedQueryBuilder(User::query(), $ids))->whereIn('id', $ids);
 
-        return $this->config('max_items') === 1 ? $query->first() : $query;
+        return $single && ! config('statamic.system.always_augment_to_query', false)
+            ? $query->first()
+            : $query;
     }
 
     public function shallowAugment($values)