fix(eloquent relations): add pivot class for BelongsToMany relations (#316)

* fix(eloquent relations): add pivot class for BelongsToMany relations

* pass resolved method return type

* update generic count to 3

* check laravel version for pivot generic

* forgot a `)`

* cs

* tests

* correct relation method in tests

* add stub

* ensure upgradability from < 12.3.0

* Move model to `Source` directory

* cs

---------

Co-authored-by: Geni Jaho <jahogeni@gmail.com>

Author: jrdnrc

src/Rector/ClassMethod/AddGenericReturnTypeToRelationsRector.php

@@ -51,6 +51,7 @@ class AddGenericReturnTypeToRelationsRector extends AbstractRector
     private const array RELATION_WITH_INTERMEDIATE_METHODS = ['hasManyThrough', 'hasOneThrough'];
 
     private bool $shouldUseNewGenerics = false;
+    private bool $shouldUsePivotGeneric = false;
 
     public function __construct(
         private readonly TypeComparator $typeComparator,
@@ -200,6 +201,7 @@ public function refactor(Node $node): ?Node
 
         // Put here to make the check as late as possible
         $this->setShouldUseNewGenerics();
+        $this->setShouldUsePivotGeneric();
 
         $classForChildGeneric = $this->getClassForChildGeneric($scope, $relationMethodCall);
         $classForIntermediateGeneric = $this->getClassForIntermediateGeneric($relationMethodCall);
@@ -221,7 +223,12 @@ public function refactor(Node $node): ?Node
 
         $genericTypeNode = new GenericTypeNode(
             new FullyQualifiedIdentifierTypeNode($methodReturnTypeName),
-            $this->getGenericTypes($relatedClass, $classForChildGeneric, $classForIntermediateGeneric),
+            $this->getGenericTypes(
+                $methodReturnType,
+                $relatedClass,
+                $classForChildGeneric,
+                $classForIntermediateGeneric
+            ),
         );
 
         // Update or add return tag
@@ -400,8 +407,8 @@ private function areGenericTypesEqual(
         $phpDocHasIntermediateGeneric = count($phpDocTypes) === 3;
 
         if ($classForIntermediateGeneric === null && ! $phpDocHasIntermediateGeneric) {
-            // If there is only one generic, it means method is using the old format. We should update it.
-            if (count($phpDocTypes) === 1) {
+            // If there are less than three generics, it means method is using the old format. We should update it.
+            if (count($phpDocTypes) < 3) {
                 return false;
             }
 
@@ -449,7 +456,7 @@ private function doesMethodHasName(MethodCall $methodCall, array $methodNames):
     /**
      * @return IdentifierTypeNode[]
      */
-    private function getGenericTypes(string $relatedClass, ?string $childClass, ?string $intermediateClass): array
+    private function getGenericTypes(Node $node, string $relatedClass, ?string $childClass, ?string $intermediateClass): array
     {
         $generics = [new FullyQualifiedIdentifierTypeNode($relatedClass)];
 
@@ -463,6 +470,13 @@ private function getGenericTypes(string $relatedClass, ?string $childClass, ?str
             }
 
             $generics[] = new IdentifierTypeNode('$this');
+
+            if ($this->shouldUsePivotGeneric && $this->isObjectType(
+                $node,
+                new ObjectType('Illuminate\Database\Eloquent\Relations\BelongsToMany')
+            )) {
+                $generics[] = new FullyQualifiedIdentifierTypeNode('\Illuminate\Database\Eloquent\Relations\Pivot');
+            }
         }
 
         return $generics;
@@ -476,4 +490,13 @@ private function setShouldUseNewGenerics(): void
             $this->shouldUseNewGenerics = version_compare($reflectionClassConstant->getValue(), '11.15.0', '>=');
         }
     }
+
+    private function setShouldUsePivotGeneric(): void
+    {
+        $reflectionClassConstant = new ReflectionClassConstant($this->applicationClass, 'VERSION');
+
+        if (is_string($reflectionClassConstant->getValue())) {
+            $this->shouldUsePivotGeneric = version_compare($reflectionClassConstant->getValue(), '12.3.0', '>=');
+        }
+    }
 }

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

@@ -0,0 +1,9 @@
+<?php
+
+namespace Illuminate\Database\Eloquent\Relations;
+
+if (class_exists('Illuminate\Database\Eloquent\Relations\BelongsToMany')) {
+    return;
+}
+
+class BelongsToMany extends Relation {}

tests/Rector/ClassMethod/AddGenericReturnTypeToRelationsRector/Fixture/NewGenerics/belongs-to-many-with-no-pivot.php.inc

@@ -0,0 +1,41 @@
+<?php
+
+namespace RectorLaravel\Tests\Rector\ClassMethod\AddGenericReturnTypeToRelationsRector\Fixture\NewGenerics;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsToMany;
+use RectorLaravel\Tests\Rector\ClassMethod\AddGenericReturnTypeToRelationsRector\Source\SomeModel;
+
+class User extends Model
+{
+    /**
+     * @return \Illuminate\Database\Eloquent\Relations\BelongsToMany<\RectorLaravel\Tests\Rector\ClassMethod\AddGenericReturnTypeToRelationsRector\Source\SomeModel, $this>
+     */
+    public function models(): BelongsToMany
+    {
+        return $this->belongsToMany(SomeModel::class);
+    }
+}
+
+?>
+-----
+<?php
+
+namespace RectorLaravel\Tests\Rector\ClassMethod\AddGenericReturnTypeToRelationsRector\Fixture\NewGenerics;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsToMany;
+use RectorLaravel\Tests\Rector\ClassMethod\AddGenericReturnTypeToRelationsRector\Source\SomeModel;
+
+class User extends Model
+{
+    /**
+     * @return \Illuminate\Database\Eloquent\Relations\BelongsToMany<\RectorLaravel\Tests\Rector\ClassMethod\AddGenericReturnTypeToRelationsRector\Source\SomeModel, $this, \Illuminate\Database\Eloquent\Relations\Pivot>
+     */
+    public function models(): BelongsToMany
+    {
+        return $this->belongsToMany(SomeModel::class);
+    }
+}
+
+?>

tests/Rector/ClassMethod/AddGenericReturnTypeToRelationsRector/Fixture/NewGenerics/belongs-to-many.php.inc

@@ -0,0 +1,38 @@
+<?php
+
+namespace RectorLaravel\Tests\Rector\ClassMethod\AddGenericReturnTypeToRelationsRector\Fixture\NewGenerics;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsToMany;
+use RectorLaravel\Tests\Rector\ClassMethod\AddGenericReturnTypeToRelationsRector\Source\SomeModel;
+
+class User extends Model
+{
+    public function models(): BelongsToMany
+    {
+        return $this->belongsToMany(SomeModel::class);
+    }
+}
+
+?>
+-----
+<?php
+
+namespace RectorLaravel\Tests\Rector\ClassMethod\AddGenericReturnTypeToRelationsRector\Fixture\NewGenerics;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsToMany;
+use RectorLaravel\Tests\Rector\ClassMethod\AddGenericReturnTypeToRelationsRector\Source\SomeModel;
+
+class User extends Model
+{
+    /**
+     * @return \Illuminate\Database\Eloquent\Relations\BelongsToMany<\RectorLaravel\Tests\Rector\ClassMethod\AddGenericReturnTypeToRelationsRector\Source\SomeModel, $this, \Illuminate\Database\Eloquent\Relations\Pivot>
+     */
+    public function models(): BelongsToMany
+    {
+        return $this->belongsToMany(SomeModel::class);
+    }
+}
+
+?>

tests/Rector/ClassMethod/AddGenericReturnTypeToRelationsRector/Source/NewApplication.php

@@ -6,5 +6,5 @@
 
 class NewApplication extends Application
 {
-    const VERSION = '11.15.0';
+    const VERSION = '12.3.0';
 }

tests/Rector/ClassMethod/AddGenericReturnTypeToRelationsRector/Source/SomeModel.php

@@ -0,0 +1,7 @@
+<?php
+
+namespace RectorLaravel\Tests\Rector\ClassMethod\AddGenericReturnTypeToRelationsRector\Source;
+
+use Illuminate\Database\Eloquent\Model;
+
+class SomeModel extends Model {}