From 0ffc6bfaab12e2d4dfcc5e1147796e8e0921d629 Mon Sep 17 00:00:00 2001
From: Pauline Vos <pauline.vos@mongodb.com>
Date: Mon, 2 Jun 2025 13:54:01 +0200
Subject: [PATCH] Add conditional return type to `Builder::raw()`

for both the Eloquent and the Query builder, so that developers can
understand that the return type will either be a `Collection` or an
`Expression` based on the argument that's passed to `raw()`
---
 src/Eloquent/Builder.php | 10 +++++++++-
 src/Query/Builder.php    |  8 +++++++-
 2 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/src/Eloquent/Builder.php b/src/Eloquent/Builder.php
index f3ffd7012..7dba7b7ab 100644
--- a/src/Eloquent/Builder.php
+++ b/src/Eloquent/Builder.php
@@ -4,10 +4,12 @@
 
 namespace MongoDB\Laravel\Eloquent;
 
+use Closure;
 use Illuminate\Database\Eloquent\Builder as EloquentBuilder;
 use Illuminate\Database\Eloquent\Collection;
 use Illuminate\Database\Eloquent\Model;
 use MongoDB\BSON\Document;
+use MongoDB\Builder\Expression;
 use MongoDB\Builder\Type\QueryInterface;
 use MongoDB\Builder\Type\SearchOperatorInterface;
 use MongoDB\Driver\CursorInterface;
@@ -229,7 +231,13 @@ public function decrement($column, $amount = 1, array $extra = [])
         return parent::decrement($column, $amount, $extra);
     }
 
-    /** @inheritdoc */
+    /**
+     * @param (Closure():T)|Expression|null $value
+     *
+     * @return ($value is Closure ? T : ($value is null ? Collection : Expression))
+     *
+     * @template T
+     */
     public function raw($value = null)
     {
         // Get raw results from the query builder.
diff --git a/src/Query/Builder.php b/src/Query/Builder.php
index 6823998fd..9a6701b87 100644
--- a/src/Query/Builder.php
+++ b/src/Query/Builder.php
@@ -964,7 +964,13 @@ public function lists($column, $key = null)
         return $this->pluck($column, $key);
     }
 
-    /** @inheritdoc */
+    /**
+     * @param (Closure():T)|Expression|null $value
+     *
+     * @return ($value is Closure ? T : ($value is null ? Collection : Expression))
+     *
+     * @template T
+     */
     public function raw($value = null)
     {
         // Execute the closure on the mongodb collection