Add conditional return type to Builder::raw() (#3395)

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()`

Author: paulinevos

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.

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