[11.x] Add generic PHPDoc to relations

[asanovr]

These changes add support to generic types for model relations.

Now, we can write types like this:

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

And we will get

$user->posts()->get() - Collection of Post
$user->posts()->make() - Model of Post

[github-actions]

Thanks for submitting a PR!

Note that draft PR's are not reviewed. If you would like a review, please mark your pull request as ready for review in the GitHub user interface.

Pull requests that are abandoned in draft may be closed due to inactivity.

[siarheipashkevich]

@nunomaduro why didn't you do it earlier? 😄

[browner12]

from a semantic perspective, don't "child" and "related" reference the same thing? Would "child" and "parent" be more appropriate?

[taylorotwell]

We don't really have any extensive type test suit here so it's hard to ship this with confidence.

[calebdw]

Most of this is likely coming from the Larastan stubs (and I've thought of attempting a PR like this several times).

However, since we're looking to add this to the framework now I do want to call attention to @nagmat84's extensive PR to fix the Larastan relation generics: larastan/larastan#1285. The PR was closed when @nunomaduro deleted the Larastan master branch and it just hasn't been reopened, but I believe it would be good to take the proposed changes under consideration.

[calebdw]

This generic name (T) isn't specific enough and should be indicative of its purpose. It's also a bad idea for child classes to override the template name and this will cause issues downstream as sometimes we grab the generic by name---introducing a name change in the inheritance chain adds unnecessary complexity.

The Larastan stubs use:

Suggested change

	* @template T of \Illuminate\Database\Eloquent\Model
	* @template TRelatedModel of \Illuminate\Database\Eloquent\Model

[calebdw]

mixed should not be used as the key type for collections---it can only be a int|string (can also use the array-key alias). However, I'd wager that most of these collection returning methods return a simple collection which would use int as the key type

Suggested change

	* @return \Illuminate\Database\Eloquent\Collection<mixed, T>
	* @return \Illuminate\Database\Eloquent\Collection<int, T>

Or if it really can return int or string keys:

Suggested change

	* @return \Illuminate\Database\Eloquent\Collection<mixed, T>
	* @return \Illuminate\Database\Eloquent\Collection<int|string, T>