[12.x] use "class-string" type for using pivot model

[browner12]

the using property of the BelongsToMany class is not just a string, but specifically a class string, so we'll document it as such.

helps in places where static methods are being called on the string

still a little new to the generics declarations, so LMK if I need to adjust anything on that.

[browner12]

if someone could point me in the right direction on the generics stuff here, that would be much appreciated. about time I get better at this stuff I guess.

[taylorotwell]

Looks like the type tests failed.

[AndrewMast]

@browner12 Take a look at browner12/framework#1 to see if that fixes the tests

[browner12]

thanks @AndrewMast for the fix!

[devfrey]

Is there any benefit to these generics in userland code? Because the new @template TPivotModel requires every reference to BelongsToMany (i.e. every model relation method) to also include the pivot type, even though (most of the time) it will be the default Pivot model.

PHPStan supports template defaults, so we could make it optional to provide a more specific class for TPivotModel using:

 /**
  * @template TPivotModel of \Illuminate\Database\Eloquent\Relations\Pivot = \Illuminate\Database\Eloquent\Relations\Pivot
  */

[amants]

@devfrey indeed. It also broke all my many-to-many relations phpstan.

Method App\Domain\User\Models\User::roles() should return Illuminate\Database\Eloquent\Relations\BelongsToMany<App\Domain\Role\Models\Role, $this(App\Domain\User\Models\User)> but returns  
         Illuminate\Database\Eloquent\Relations\BelongsToMany<App\Domain\Role\Models\Role, $this(App\Domain\User\Models\User), Illuminate\Database\Eloquent\Relations\Pivot>.                         
         🪪  return.type  

When adding Pivot to the PHPDoc:

Generic type Illuminate\Database\Eloquent\Relations\BelongsToMany<App\Domain\Role\Models\Role, $this(App\Domain\User\Models\User), Illuminate\Database\Eloquent\Relations\Pivot> in PHPDoc tag @return specifies 3 template types, but  
         class Illuminate\Database\Eloquent\Relations\BelongsToMany supports only 2: TRelatedModel, TDeclaringModel    

[AJenbo]

@amants the problem is that Larastan also needs to be updated: https://github.com/larastan/larastan/blob/3.x/stubs/common/BelongsToMany.stub maybe @calebdw can help with this?

The default suggested by @devfrey will probably serve to allow it to work with the older Larastan.

[calebdw]

I had thought about something similar to enable the pivot property to work correctly: larastan/larastan#1774

However, the template should use a default to prevent every userland relationship from having to define it

[AJenbo]

I updated the stub in Larastan, I have tested that this indeed resolves the issue: larastan/larastan#2231

Having the default there is also enough to avoid having users needing to document it, but it should probably be made a default in both places.

[calebdw]

I'm working on a PR for the framework right now to fix some things with this implementation