PHPORM-492 Fix PHPDoc return and param types for raw() methods (#3526)

* Fix PHPDoc return and param types for raw() methods

The @param type for the Closure argument was missing the \MongoDB\Collection
parameter that is passed at runtime. The @return type for the null case
incorrectly referenced Illuminate Collection classes instead of \MongoDB\Collection.
For Eloquent\Builder::raw(), the Closure case was also missing TModel and
Collection<int, TModel> as possible return types, which caused static analysis
tools to report false positives when the result was used as a model.

* Add PHPStan type tests for Builder::raw() param and return types

* Remove weak closure parameter tests from BuilderRawTypes

* Fix Expression return type in Eloquent\Builder::raw() and add Expression tests

The @return PHPDoc for the non-Closure/non-null case referenced MongoDB\Builder\Expression
(the local import) but the method delegates to Query\Builder::raw() which wraps the value
in a new Illuminate\Database\Query\Expression.

* Use Illuminate\Contracts\Database\Query\Expression in Eloquent\Builder::raw() return type

$this->query is declared as Illuminate\Database\Query\Builder, whose raw() returns
the Illuminate\Contracts\Database\Query\Expression interface, not the concrete class.

Author: GromNaN

src/Eloquent/Builder.php

@@ -223,9 +223,9 @@ public function decrement($column, $amount = 1, array $extra = [])
     }
 
     /**
-     * @param (Closure():T)|Expression|null $value
+     * @param (Closure(\MongoDB\Collection):T)|Expression|null $value
      *
-     * @return ($value is Closure ? T : ($value is null ? Collection : Expression))
+     * @return ($value is Closure ? (T is CursorInterface ? Collection<int, TModel> : T|TModel|Collection<int, TModel>) : ($value is null ? \MongoDB\Collection : \Illuminate\Contracts\Database\Query\Expression))
      *
      * @template T
      */

src/Query/Builder.php

@@ -1045,9 +1045,9 @@ public function lists($column, $key = null)
     }
 
     /**
-     * @param (Closure():T)|Expression|null $value
+     * @param (Closure(\MongoDB\Collection):T)|Expression|null $value
      *
-     * @return ($value is Closure ? T : ($value is null ? Collection : Expression))
+     * @return ($value is Closure ? T : ($value is null ? \MongoDB\Collection : Expression))
      *
      * @template T
      */

tests/PHPStan/BuilderRawTypes.php

@@ -0,0 +1,73 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MongoDB\Laravel\Tests\PHPStan;
+
+use Illuminate\Database\Query\Expression;
+use MongoDB\Collection as MongoDBCollection;
+use MongoDB\Laravel\Eloquent\Builder as EloquentBuilder;
+use MongoDB\Laravel\Query\Builder as QueryBuilder;
+use MongoDB\Laravel\Tests\Models\User;
+
+use function PHPStan\Testing\assertType;
+
+/**
+ * PHPStan type-level tests for Builder::raw() return and param types.
+ * These functions are never executed at runtime — they exist to let PHPStan
+ * validate that the @param and @return types on raw() match the declared signatures.
+ */
+final class BuilderRawTypes
+{
+    public static function queryBuilderRawNull(QueryBuilder $queryBuilder): void
+    {
+        assertType('MongoDB\Collection', $queryBuilder->raw());
+    }
+
+    public static function queryBuilderRawClosureFind(QueryBuilder $queryBuilder): void
+    {
+        assertType('MongoDB\Driver\CursorInterface', $queryBuilder->raw(fn (MongoDBCollection $c) => $c->find([])));
+    }
+
+    public static function queryBuilderRawClosureFindOne(QueryBuilder $queryBuilder): void
+    {
+        assertType('array|object|null', $queryBuilder->raw(fn (MongoDBCollection $c) => $c->findOne([])));
+    }
+
+    public static function queryBuilderRawExpression(QueryBuilder $queryBuilder): void
+    {
+        assertType('Illuminate\Database\Query\Expression', $queryBuilder->raw(new Expression('foo')));
+    }
+
+    /** @param EloquentBuilder<User> $builder */
+    public static function eloquentBuilderRawNull(EloquentBuilder $builder): void
+    {
+        assertType('MongoDB\Collection', $builder->raw());
+    }
+
+    /** @param EloquentBuilder<User> $builder */
+    public static function eloquentBuilderRawClosureFind(EloquentBuilder $builder): void
+    {
+        assertType(
+            'Illuminate\Database\Eloquent\Collection<int, MongoDB\Laravel\Tests\Models\User>',
+            $builder->raw(fn (MongoDBCollection $c) => $c->find([])),
+        );
+    }
+
+    /** @param EloquentBuilder<User> $builder */
+    public static function eloquentBuilderRawExpression(EloquentBuilder $builder): void
+    {
+        assertType('Illuminate\Contracts\Database\Query\Expression', $builder->raw(new Expression('foo')));
+    }
+
+    /** @param EloquentBuilder<User> $builder */
+    public static function eloquentBuilderRawClosureFindOne(EloquentBuilder $builder): void
+    {
+        // PHPStan simplifies User|Collection<int, User>|array|object|null to array|object|null
+        // because object is a supertype of User and Collection.
+        assertType(
+            'array|object|null',
+            $builder->raw(fn (MongoDBCollection $c) => $c->findOne([])),
+        );
+    }
+}