Add annotations to query building classes

In order to help with auto-completion when users build queries from our
document models.

Author: paulinevos

src/Eloquent/Builder.php

@@ -31,6 +31,9 @@
 /**
  * @method \MongoDB\Laravel\Query\Builder toBase()
  * @template TModel of Model
+ * @extends EloquentBuilder<TModel>
+ *
+ * @mixin \MongoDB\Laravel\Query\Builder
  */
 class Builder extends EloquentBuilder
 {
@@ -69,7 +72,7 @@ class Builder extends EloquentBuilder
     ];
 
     /**
-     * @return ($function is null ? AggregationBuilder : self)
+     * @return ($function is null ? AggregationBuilder : $this)
      *
      * @inheritdoc
      */

src/Eloquent/DocumentModel.php

@@ -50,6 +50,19 @@
 use function strlen;
 use function var_export;
 
+/**
+ * @method static QueryBuilder query()
+ * @method static self sole(array $columns)
+ * @method static bool truncate()
+ * @method static QueryBuilder where(Closure|string|array|Expression $column, mixed $operator = null, mixed $value = null, string $boolean = 'and')
+ * @method static QueryBuilder whereBetween(string $column, iterable $values, string $boolean = null, bool $not = null)
+ * @method static QueryBuilder whereIn(...$parameters, mixed $values, string $boolean = null, bool $not = null)
+ * @method static QueryBuilder whereNot(array|Closure|Expression|string $column, $operator = null, $value = null, $boolean = 'and')
+ * @method static QueryBuilder whereNotIn(...$parameters)
+ * @method static QueryBuilder whereNotNull(...$parameters)
+ * @method static QueryBuilder whereNull(string $value)
+ * @mixin Eloquent
+ */
 trait DocumentModel
 {
     use HybridRelations;
@@ -553,8 +566,12 @@ public function getParentRelation(): ?Relation
         return $this->parentRelation ?? null;
     }
 
-    /** @inheritdoc */
-    public function newEloquentBuilder($query)
+    /**
+     * @param $query
+     * @return Builder
+     */
+    #[Override]
+    public function newEloquentBuilder($query): Builder
     {
         return new Builder($query);
     }
@@ -566,7 +583,7 @@ public function qualifyColumn($column)
     }
 
     /** @inheritdoc */
-    protected function newBaseQueryBuilder()
+    protected function newBaseQueryBuilder(): QueryBuilder
     {
         $connection = $this->getConnection();
 

tests/Models/Anniversary.php

@@ -7,15 +7,11 @@
 use Illuminate\Database\Eloquent\Model;
 use MongoDB\Laravel\Eloquent\DocumentModel;
 use MongoDB\Laravel\Eloquent\Model as Eloquent;
-use MongoDB\Laravel\Query\Builder;
 
 /**
  * @property string $name
  * @property string $anniversary
  * @mixin Eloquent
- * @method static Builder create(...$values)
- * @method static Builder truncate()
- * @method static Eloquent sole(...$parameters)
  */
 class Anniversary extends Model
 {

tests/Models/HiddenAnimal.php

@@ -6,17 +6,11 @@
 
 use Illuminate\Database\Eloquent\Model;
 use MongoDB\Laravel\Eloquent\DocumentModel;
-use MongoDB\Laravel\Eloquent\Model as Eloquent;
-use MongoDB\Laravel\Query\Builder;
 
 /**
  * @property string $name
  * @property string $country
  * @property bool $can_be_eaten
- * @mixin Eloquent
- * @method static Builder create(...$values)
- * @method static Builder truncate()
- * @method static Eloquent sole(...$parameters)
  */
 final class HiddenAnimal extends Model
 {