[11.x] Fix incorrect PHPDoc for Builder relation

[kayw-geek]

In PHPStan, the parameters in a Closure are non-covariant by default. So, when you define a Closure with a parameter type-hinted as a subclass of Relation, PHPStan will throw the following error:

expects 
array<(Closure(Illuminate\Database\Eloquent\Relations\Relation<*, *, *>): mixed)|string>|string, 
array<string, Closure(Illuminate\Database\Eloquent\Relations\HasOne): void} given

This issue may be caused by #52729

[staudenmeir]

/cc @calebdw

[Plytas]

Also, I'm pretty sure it doesn't work with nested eager loading as the value in the array can be another array.

[calebdw]

@kayw-geek,

This will not work---I believe call-site variance only works for generics (e.g., Collection<int, covariant Foo>)

• https://phpstan.org/r/f046db64-33b9-45cc-8a1e-25eec6ca1120

Perhaps this is something @ondrejmirtes might consider supporting?

In the meantime you can simply change your closure to specify the Relation instead of HasOne:

- $query->with(['foo' => fn (HasOne $q) => $q]);
+ $query->with(['foo' => fn (Relation $q) => $q]);

[calebdw]

@Plytas,

Also, I'm pretty sure it doesn't work with nested eager loading as the value in the array can be another array.

Recursive array types are a bit painful, I'll add array to the definition and then open a PHPStan issue to see if it would be possible to get an array-rec type

[kayw-geek]

PHPStan playground is not support, but PHPStan program is supported.

[calebdw]

PHPStan playground is not support, but PHPStan program is supported.

Sorry, you're mistaken here---the playground is the phpstan program. The only reason why you're not seeing errors is that the framework phpstan level is too low,, This results in a phpstan parse error and it now knows nothing about the parameter type

[kayw-geek]

@calebdw
I want to more accurate native type hint in my project.

[Plytas]

@calebdw I think array will be fine for now.

Regarding using Relation as type hint:

In the meantime you can simply change your closure to specify the Relation instead of HasOne:

- $query->with(['foo' => fn (HasOne $q) => $q]);
+ $query->with(['foo' => fn (Relation $q) => $q]);

There's a slight issue with it if you need to perform other operations on the inner query like ->select() or ->where(). PHPstan will complain that those methods are not available on Relation.

[calebdw]

@Plytas, the Relation forwards those method to the mixed in Builder

[Plytas]

It does on runtime, but I wan't able to get PHPstan happy with it.

[calebdw]

It does on runtime, but I wan't able to get PHPstan happy with it.

Then there's a bug somewhere, but it does work: https://phpstan.org/r/a17bc6f0-ca28-4dd5-9c66-fbebf28db054

[Plytas]

Thanks for going extra length to confirm it. I'll try to debug why it's not working on my end.

[calebdw]

Might be an issue with Larastan

[Plytas]

@calebdw just an FYI. I believe you're right about it being Larastan issue. It's missing the @mixin annotation.

https://github.com/larastan/larastan/blob/2.x/stubs/common/Relation.stub

[calebdw]

Larastan has ClassReflectionExtensions that handle the mixin magic---please raise an issue over there and I'll look into it