Add PHPDoc @template to eloquent Builder

[zlodes]

It will improve static analysis tools and IDEs knowledge about types.

Code example:

$userQuery = User::query(); // returns Builder. Will return Builder<T> (Builder<User>)

// It's the worst example with find:
$user = $userQuery->find(42); // returns Model|Collection|static[]|static|null. Will return T|null (User|null)

$userCollection = $userQuery->get(); // returns Collection|static[]. Will return Collection<int, User>

Now IDE and some static analysis tools cannot recognize types and we need to write something like this:

class UserRepository implements UserRepositoryInterface
{
    // ...

    public function getUserById(int $id): ?User
    {
        /** @var ?User $user */
        $user = User::query()
            ->find($id);

        return $user;
    }
}

I know how to do it. I can make a PR if the idea will be approved.

[oopok]

It's a good idea, and I think relationships might need generics support too.
Example:

// Builder contract declaration:
/**
 * @template T of \Illuminate\Database\Eloquent\Model
 * @mixin T
 * @mixin \Illuminate\Database\Eloquent\Builder
 */
interface Builder extends BaseContract
{ }

// Relationship methods declaration:
trait HasRelationships
{
    /**
     * Define an inverse one-to-one or many relationship.
     *
     * @template T of \Illuminate\Database\Eloquent\Model
     * @param class-string<T> $related
     * @param string|null $foreignKey
     * @param string|null $localKey
     * @return \Illuminate\Database\Eloquent\Relations\HasMany<T>
     */
    public function hasMany($related, $foreignKey = null, $localKey = null)
    {
        // ...
    }

    // Other relationship mehtods ...
}

// Usage:
class User extends Model
{
    public function posts()
    {
        return $this->hasMany(Post::class); // Will return HasMany<User>
    }
}

// Now, we can use static analysis tools on relation builder of Post
// User::first()->posts()->...

[lwohlhart]

strong approval 😉

[lwohlhart]

Just fyi, the larastan implementation provides a solution

https://github.com/nunomaduro/larastan/blob/master/tests/Features/Models/Relations.php

https://github.com/nunomaduro/larastan/blob/master/stubs/HasManyThrough.stub

[puggan]

Made a PR with the suggested changes: #46169