Broken BelongsToMany type definitions

[amants]

Laravel Version

12.3

PHP Version

8.4

Database Driver & Version

No response

Description

Ever since the last update, all of the many to many relations in my project have broken linting definitions.

Original code:

    /**
     * @return BelongsToMany<Role, $this>
     */
    public function roles(): BelongsToMany
    {
        return $this->belongsToMany(Role::class, 'user_role');
    }

Linting error:

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:

    /**
     * @return BelongsToMany<Role, $this, Illuminate\Database\Eloquent\Relations\Pivot>
     */
    public function roles(): BelongsToMany
    {
        return $this->belongsToMany(Role::class, 'user_role');
    }

Linting error:

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    

Steps To Reproduce

Create a model with a many-to-many relationship.

Declare the phpdoc like:

    /**
     * @return BelongsToMany<Role, $this>
     */

Run phpstan with level 9.

[AJenbo]

It's not broken, the issue you are having is that your using Larastan which has an outdated stub that overwrites the definition https://github.com/larastan/larastan/blob/3.x/stubs/common/BelongsToMany.stub

Setting a default value for the template should allow it to be compatible with the Larastan stub and then once Larastan updates the stub you can also start using it.

[devfrey]

It's not broken, the issue you are having is that your using Larastan which has an outdated stub that overwrites the definition larastan/larastan@3.x/stubs/common/BelongsToMany.stub

Setting a default value for the template should allow it to be compatible with the Larastan stub and then once Larastan updates the stub you can also start using it.

I don't use Larastan and I still have this issue. This needs to be addressed in the framework.

[AJenbo]

@devfrey maybe you are conflating this with having to set the pivot class on the relation? If I set the pivot class and do not have Larastan active then there aren't any issues, if I then activate Larastan I get the error described in this issue.

Setting a default class in the framework is a related but different topic.

[amants]

@AJenbo I was kind of hinting to that being an issue as well. We have a ton of many to many relations to manage and it's not clean to have to add the default Pivot class on all relations.
I should have thought more about writing the issue and added that to the issue more clearly in the first place.

[AJenbo]

That might be annoying, but it's not broken. And my understanding is that that is also being addressed elsewhere. I also have lots of relations and will be happy for that change, but lets keep things separate.

[amants]

@AJenbo Which is a breaking change without being mentioned.

[AJenbo]

The PR for addressing the need to set the pivot class is now ready as well #55086