Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[11.x] Add generic PHPDoc to relations #51681

Closed
wants to merge 4 commits into from
Closed

Conversation

asanovr
Copy link

@asanovr asanovr commented Jun 2, 2024

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

Copy link

github-actions bot commented Jun 2, 2024

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.

@asanovr asanovr marked this pull request as ready for review June 3, 2024 05:51
@siarheipashkevich
Copy link
Contributor

siarheipashkevich commented Jun 4, 2024

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

@browner12
Copy link
Contributor

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

@taylorotwell
Copy link
Member

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

@taylorotwell taylorotwell marked this pull request as draft June 5, 2024 16:04
@calebdw
Copy link
Contributor

calebdw commented Jun 13, 2024

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.

@@ -13,6 +13,9 @@
use Illuminate\Support\Traits\ForwardsCalls;
use Illuminate\Support\Traits\Macroable;

/**
* @template T of \Illuminate\Database\Eloquent\Model
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@@ -157,7 +160,7 @@ abstract public function getResults();
/**
* Get the relationship for eager loading.
*
* @return \Illuminate\Database\Eloquent\Collection
* @return \Illuminate\Database\Eloquent\Collection<mixed, T>
Copy link
Contributor

@calebdw calebdw Jun 13, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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>

@driesvints driesvints changed the title Add generic PHPDoc to relations [11.x] Add generic PHPDoc to relations Jun 21, 2024
@calebdw
Copy link
Contributor

calebdw commented Jul 10, 2024

@asanovr, @driesvints, this can be closed now that #51851 has been merged

@driesvints
Copy link
Member

Thanks @calebdw

@driesvints driesvints closed this Jul 26, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

6 participants