feat: adds conditional return types to some Builder methods (#1236)

CHANGELOG.md

@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 ## [Unreleased]
 * fix: when/unless callback for default value can return void
 
+### Improvements
+* feat: Added conditional return types
+
 ### Fixes
 
 * fix: Change QueryBuilder::newQuery() @return from `$this` to `static`

stubs/BelongsToMany.stub

@@ -13,7 +13,7 @@ class BelongsToMany extends Relation
      *
      * @param  mixed  $id
      * @param  array<int, (model-property<TRelatedModel>|'*')>|model-property<TRelatedModel>|'*'  $columns
-     * @return \Illuminate\Support\Collection<int, TRelatedModel>|TRelatedModel
+     * @return ($id is (\Illuminate\Contracts\Support\Arrayable<array-key, mixed>|array<mixed>) ? \Illuminate\Support\Collection<int, TRelatedModel> : TRelatedModel)
      */
     public function findOrNew($id, $columns = ['*']);
 
@@ -51,7 +51,7 @@ class BelongsToMany extends Relation
      *
      * @param  mixed  $id
      * @param  array<int, mixed>  $columns
-     * @return TRelatedModel|\Illuminate\Database\Eloquent\Collection<int, TRelatedModel>|null
+     * @return ($id is (\Illuminate\Contracts\Support\Arrayable<array-key, mixed>|array<mixed>) ? \Illuminate\Database\Eloquent\Collection<int, TRelatedModel> : TRelatedModel)|null
      */
     public function find($id, $columns = ['*']);
 
@@ -69,7 +69,7 @@ class BelongsToMany extends Relation
      *
      * @param  mixed  $id
      * @param  array<int, mixed>  $columns
-     * @return TRelatedModel|\Illuminate\Database\Eloquent\Collection<int, TRelatedModel>
+     * @return ($id is (\Illuminate\Contracts\Support\Arrayable<array-key, mixed>|array<mixed>) ? \Illuminate\Database\Eloquent\Collection<int, TRelatedModel> : TRelatedModel)
      *
      * @throws \Illuminate\Database\Eloquent\ModelNotFoundException
      */

stubs/EloquentBuilder.stub

@@ -64,7 +64,7 @@ class Builder
      *
      * @param  mixed  $id
      * @param  array<int, (model-property<TModelClass>|'*')>|model-property<TModelClass>|'*'  $columns
-     * @phpstan-return TModelClass|\Illuminate\Database\Eloquent\Collection<int, TModelClass>|null
+     * @phpstan-return ($id is (\Illuminate\Contracts\Support\Arrayable<array-key, mixed>|array<mixed>) ? \Illuminate\Database\Eloquent\Collection<int, TModelClass> : TModelClass)|null
      */
     public function find($id, $columns = ['*']);
 
@@ -82,7 +82,7 @@ class Builder
      *
      * @param  mixed  $id
      * @param  array<int, (model-property<TModelClass>|'*')>|model-property<TModelClass>|'*'  $columns
-     * @phpstan-return TModelClass|\Illuminate\Database\Eloquent\Collection<int, TModelClass>
+     * @phpstan-return ($id is (\Illuminate\Contracts\Support\Arrayable<array-key, mixed>|array<mixed>) ? \Illuminate\Database\Eloquent\Collection<int, TModelClass> : TModelClass)
      *
      * @throws \Illuminate\Database\Eloquent\ModelNotFoundException
      */

stubs/HasOneOrMany.stub

@@ -30,7 +30,7 @@ abstract class HasOneOrMany extends Relation
      *
      * @param  mixed  $id
      * @param  array<int, mixed>  $columns
-     * @return \Illuminate\Support\Collection<int, TRelatedModel>|TRelatedModel
+     * @return ($id is (\Illuminate\Contracts\Support\Arrayable<array-key, mixed>|array<mixed>) ? \Illuminate\Support\Collection<int, TRelatedModel> : TRelatedModel)
      */
     public function findOrNew($id, $columns = ['*']);