Document array usages for find methods

Neol3108 · Neol3108 · commit 7a9974f0b5d9 · 2024-05-03T21:24:15.000+02:00
diff --git a/stubs/database/eloquent/builder.stub b/stubs/database/eloquent/builder.stub
@@ -57,15 +57,15 @@ class Builder implements BuilderContract
     /**
      * @param mixed $id
      * @param string[]|string $columns
-     * @return TModel
+     * @return ($id is \Illuminate\Contracts\Support\Arrayable<array-key, mixed>|array<mixed> ? TCollection : TModel)
      * @throws \Illuminate\Database\Eloquent\ModelNotFoundException<TModel>
      */
     public function findOrFail($id, $columns = ['*']);
 
     /**
      * @param mixed $id
      * @param string[]|string $columns
-     * @return TModel
+     * @return ($id is \Illuminate\Contracts\Support\Arrayable<array-key, mixed>|array<mixed> ? TCollection : TModel)
      */
     public function findOrNew($id, $columns = ['*']);
 
diff --git a/stubs/database/eloquent/relations/belongs-to-many.stub b/stubs/database/eloquent/relations/belongs-to-many.stub
@@ -15,7 +15,7 @@ class BelongsToMany extends Relation
     /**
      * @param mixed $id
      * @param string[] $columns
-     * @return TRelated
+     * @return ($id is \Illuminate\Contracts\Support\Arrayable<array-key, mixed>|array<mixed> ? TRelatedCollection : TRelated)
      */
     public function findOrNew($id, $columns = ['*']);
 
@@ -56,7 +56,7 @@ class BelongsToMany extends Relation
     /**
      * @param mixed $id
      * @param string[] $columns
-     * @return TRelated|null
+     * @return ($id is \Illuminate\Contracts\Support\Arrayable<array-key, mixed>|array<mixed> ? TRelatedCollection : TRelated|null)
      */
     public function find($id, $columns = ['*']);
 
@@ -70,17 +70,17 @@ class BelongsToMany extends Relation
     /**
      * @param mixed $id
      * @param string[] $columns
-     * @return TRelated
+     * @return ($id is \Illuminate\Contracts\Support\Arrayable<array-key, mixed>|array<mixed> ? TRelatedCollection : TRelated)
      * @throws \Illuminate\Database\Eloquent\ModelNotFoundException<TRelated>
      */
     public function findOrFail($id, $columns = ['*']);
 
     /**
-     * @template TOther
+     * @template TReturn
      * @param mixed $id
-     * @param \Closure(): TOther|array $columns
-     * @param \Closure(): TOther|null  $callback
-     * @return TRelated|TOther
+     * @param (\Closure(): TReturn)|array $columns
+     * @param (\Closure(): TReturn)|null $callback
+     * @return ($id is \Illuminate\Contracts\Support\Arrayable<array-key, mixed>|array<mixed> ? TRelatedCollection : TRelated|TReturn)
      */
     public function findOr($id, $columns = ['*'], ?Closure $callback = null);
 
diff --git a/stubs/database/eloquent/relations/has-one-or-many.stub b/stubs/database/eloquent/relations/has-one-or-many.stub
@@ -27,7 +27,7 @@ abstract class HasOneOrMany extends Relation
     /**
      * @param mixed $id
      * @param string[] $columns
-     * @return TRelated
+     * @return ($id is \Illuminate\Contracts\Support\Arrayable<array-key, mixed>|array<mixed> ? TRelatedCollection : TRelated)
      */
     public function findOrNew($id, $columns = ['*']);
 
diff --git a/tests/Types/data/database/eloquent/relations/belongs-to-many.php b/tests/Types/data/database/eloquent/relations/belongs-to-many.php
@@ -6,14 +6,20 @@
 /** @var \Tests\Types\Fakes\Category $category */
 
 assertType('Tests\Types\Fakes\Category', $relation->findOrNew(1));
+assertType('Illuminate\Database\Eloquent\Collection<int, Tests\Types\Fakes\Category>', $relation->findOrNew([1]));
 assertType('Tests\Types\Fakes\Category', $relation->firstOrNew());
 assertType('Tests\Types\Fakes\Category', $relation->firstOrCreate());
 assertType('Tests\Types\Fakes\Category', $relation->createOrFirst());
 assertType('Tests\Types\Fakes\Category', $relation->updateOrCreate(['foo' => 'bar']));
 assertType('Tests\Types\Fakes\Category|null', $relation->find(1));
+assertType('Illuminate\Database\Eloquent\Collection<int, Tests\Types\Fakes\Category>', $relation->find([1]));
 assertType('Illuminate\Database\Eloquent\Collection<int, Tests\Types\Fakes\Category>', $relation->findMany([1]));
 assertType('Tests\Types\Fakes\Category', $relation->findOrFail(1));
+assertType('Illuminate\Database\Eloquent\Collection<int, Tests\Types\Fakes\Category>', $relation->findOrFail([1]));
 assertType('string|Tests\Types\Fakes\Category', $relation->findOr(1, fn () => 'foo-bar'));
+assertType('string|Tests\Types\Fakes\Category', $relation->findOr(1, fn () => 'foo-bar'));
+assertType('Illuminate\Database\Eloquent\Collection<int, Tests\Types\Fakes\Category>', $relation->findOr([1], ['*'], fn () => 'foo-bar'));
+assertType('Illuminate\Database\Eloquent\Collection<int, Tests\Types\Fakes\Category>', $relation->findOr([1], fn () => 'foo-bar'));
 assertType('Tests\Types\Fakes\Category|null', $relation->firstWhere('foo', 'bar'));
 assertType('Tests\Types\Fakes\Category|null', $relation->first());
 assertType('Tests\Types\Fakes\Category', $relation->firstOrFail());
diff --git a/tests/Types/data/database/eloquent/relations/has-one-or-many.php b/tests/Types/data/database/eloquent/relations/has-one-or-many.php
@@ -8,6 +8,7 @@
 assertType('Tests\Types\Fakes\Post', $relation->make(['foo' => 'bar']));
 assertType('Illuminate\Database\Eloquent\Collection<int, Tests\Types\Fakes\Post>', $relation->makeMany([['foo' => 'bar']]));
 assertType('Tests\Types\Fakes\Post', $relation->findOrNew(1));
+assertType('Illuminate\Database\Eloquent\Collection<int, Tests\Types\Fakes\Post>', $relation->findOrNew([1]));
 assertType('Tests\Types\Fakes\Post', $relation->firstOrNew(['foo' => 'bar']));
 assertType('Tests\Types\Fakes\Post', $relation->firstOrCreate(['foo' => 'bar']));
 assertType('Tests\Types\Fakes\Post', $relation->createOrFirst(['foo' => 'bar']));
