[12.x] use "class-string" type for using pivot model (#55053)

* use "class-string" type for `using` pivot model

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](https://github.com/laravel/framework/blob/12.x/src/Illuminate/Database/Eloquent/Relations/MorphToMany.php#L160)

* Update src/Illuminate/Database/Eloquent/Relations/BelongsToMany.php

apparently can't use Traits as types

Co-authored-by: Jeffrey Angenent <[email protected]>

* fixed docblocks for generic to pass type test

---------

Co-authored-by: Jeffrey Angenent <[email protected]>
Co-authored-by: Andrew Mast <[email protected]>

Author: 3 people

src/Illuminate/Database/Eloquent/Concerns/HasRelationships.php

@@ -564,7 +564,7 @@ protected function newMorphMany(Builder $query, Model $parent, $type, $id, $loca
      * @param  string|null  $parentKey
      * @param  string|null  $relatedKey
      * @param  string|null  $relation
-     * @return \Illuminate\Database\Eloquent\Relations\BelongsToMany<TRelatedModel, $this>
+     * @return \Illuminate\Database\Eloquent\Relations\BelongsToMany<TRelatedModel, $this, \Illuminate\Database\Eloquent\Relations\Pivot>
      */
     public function belongsToMany(
         $related,
@@ -624,7 +624,7 @@ public function belongsToMany(
      * @param  string  $parentKey
      * @param  string  $relatedKey
      * @param  string|null  $relationName
-     * @return \Illuminate\Database\Eloquent\Relations\BelongsToMany<TRelatedModel, TDeclaringModel>
+     * @return \Illuminate\Database\Eloquent\Relations\BelongsToMany<TRelatedModel, TDeclaringModel, \Illuminate\Database\Eloquent\Relations\Pivot>
      */
     protected function newBelongsToMany(
         Builder $query,

src/Illuminate/Database/Eloquent/Relations/BelongsToMany.php

@@ -20,6 +20,7 @@
 /**
  * @template TRelatedModel of \Illuminate\Database\Eloquent\Model
  * @template TDeclaringModel of \Illuminate\Database\Eloquent\Model
+ * @template TPivotModel of \Illuminate\Database\Eloquent\Relations\Pivot
  *
  * @extends \Illuminate\Database\Eloquent\Relations\Relation<TRelatedModel, TDeclaringModel, \Illuminate\Database\Eloquent\Collection<int, TRelatedModel>>
  */
@@ -128,7 +129,7 @@ class BelongsToMany extends Relation
     /**
      * The class name of the custom pivot model to use for the relationship.
      *
-     * @var string
+     * @var class-string<TPivotModel>
      */
     protected $using;
 
@@ -316,7 +317,7 @@ protected function buildDictionary(EloquentCollection $results)
     /**
      * Get the class being used for pivot models.
      *
-     * @return string
+     * @return class-string<TPivotModel>
      */
     public function getPivotClass()
     {
@@ -326,7 +327,7 @@ public function getPivotClass()
     /**
      * Specify the custom pivot model to use for the relationship.
      *
-     * @param  string  $class
+     * @param  class-string<TPivotModel>  $class
      * @return $this
      */
     public function using($class)

src/Illuminate/Database/Eloquent/Relations/MorphToMany.php

@@ -11,7 +11,7 @@
  * @template TRelatedModel of \Illuminate\Database\Eloquent\Model
  * @template TDeclaringModel of \Illuminate\Database\Eloquent\Model
  *
- * @extends \Illuminate\Database\Eloquent\Relations\BelongsToMany<TRelatedModel, TDeclaringModel>
+ * @extends \Illuminate\Database\Eloquent\Relations\BelongsToMany<TRelatedModel, TDeclaringModel, \Illuminate\Database\Eloquent\Relations\Pivot>
  */
 class MorphToMany extends BelongsToMany
 {

types/Database/Eloquent/Relations.php

@@ -41,7 +41,7 @@ function test(User $user, Post $post, Comment $comment, ChildUser $child): void
     assertType('Illuminate\Types\Relations\Post|false', $user->posts()->save(new Post()));
     assertType('Illuminate\Types\Relations\Post|false', $user->posts()->saveQuietly(new Post()));
 
-    assertType('Illuminate\Database\Eloquent\Relations\BelongsToMany<Illuminate\Types\Relations\Role, Illuminate\Types\Relations\User>', $user->roles());
+    assertType('Illuminate\Database\Eloquent\Relations\BelongsToMany<Illuminate\Types\Relations\Role, Illuminate\Types\Relations\User, Illuminate\Database\Eloquent\Relations\Pivot>', $user->roles());
     assertType('Illuminate\Database\Eloquent\Collection<int, Illuminate\Types\Relations\Role>', $user->roles()->getResults());
     assertType('Illuminate\Database\Eloquent\Collection<int, Illuminate\Types\Relations\Role>', $user->roles()->find([1]));
     assertType('Illuminate\Database\Eloquent\Collection<int, Illuminate\Types\Relations\Role>', $user->roles()->findMany([1, 2, 3]));
@@ -157,11 +157,11 @@ public function latestPost(): HasOne
         return $post;
     }
 
-    /** @return BelongsToMany<Role, $this> */
+    /** @return BelongsToMany<Role, $this, \Illuminate\Database\Eloquent\Relations\Pivot> */
     public function roles(): BelongsToMany
     {
         $belongsToMany = $this->belongsToMany(Role::class);
-        assertType('Illuminate\Database\Eloquent\Relations\BelongsToMany<Illuminate\Types\Relations\Role, $this(Illuminate\Types\Relations\User)>', $belongsToMany);
+        assertType('Illuminate\Database\Eloquent\Relations\BelongsToMany<Illuminate\Types\Relations\Role, $this(Illuminate\Types\Relations\User), Illuminate\Database\Eloquent\Relations\Pivot>', $belongsToMany);
 
         return $belongsToMany;
     }