[5.x] Add always_augment_to_query option (#11086)

Co-authored-by: Jason Varga <jason@pixelfear.com>

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

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)

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)

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)

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)