Fix relation types

CHANGELOG.md

@@ -5,6 +5,8 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
+
+* added: The `Relation`-related classes now required up to four template parameters instead of one: `TRelatedModel` (required as before), `TDeclaringModel` (required), `TResult` (required by base classes like `HasOneOrMany`, not required by user-facing classes like `HasMany`) and `TIntermediateModel` (only required by `...Through...`-relations) https://github.com/nunomaduro/larastan/pull/1285  
 * fix: Resolve correct model factory instance when application namespace is empty
 
 ### Fixed

src/Methods/BuilderHelper.php

@@ -74,11 +74,11 @@ public function dynamicWhere(
             $returnClassReflection = $returnObject->getClassReflection();
 
             if ($returnClassReflection !== null) {
-                $modelType = $returnClassReflection->getActiveTemplateTypeMap()->getType('TModelClass');
-
-                if ($modelType === null) {
-                    $modelType = $returnClassReflection->getActiveTemplateTypeMap()->getType('TRelatedModel');
-                }
+                $templateTypeMap = $returnClassReflection->getActiveTemplateTypeMap();
+                $modelType =
+                    $templateTypeMap->getType('TModelClass') ??
+                    $templateTypeMap->getType('TRelatedModel') ??
+                    $templateTypeMap->getType('TDeclaringModel');
 
                 if ($modelType !== null) {
                     $finder = substr($methodName, 5);

src/Methods/EloquentBuilderForwardsCallsExtension.php

@@ -18,9 +18,7 @@
 use PHPStan\ShouldNotHappenException;
 use PHPStan\Type\Generic\GenericObjectType;
 use PHPStan\Type\Generic\TemplateMixedType;
-use PHPStan\Type\Generic\TemplateObjectType;
 use PHPStan\Type\IntegerType;
-use PHPStan\Type\ObjectType;
 use PHPStan\Type\Type;
 use PHPStan\Type\TypeWithClassName;
 
@@ -77,22 +75,18 @@ private function findMethod(ClassReflection $classReflection, string $methodName
             return null;
         }
 
+        $templateTypeMap = $classReflection->getActiveTemplateTypeMap();
         /** @var Type|TemplateMixedType|null $modelType */
-        $modelType = $classReflection->getActiveTemplateTypeMap()->getType('TModelClass');
+        $modelType =
+            $templateTypeMap->getType('TModelClass') ??
+            $templateTypeMap->getType('TRelatedModel') ??
+            $templateTypeMap->getType('TDeclaringModel');
 
         // Generic type is not specified
         if ($modelType === null) {
             return null;
         }
 
-        if ($modelType instanceof TemplateObjectType) {
-            $modelType = $modelType->getBound();
-
-            if ($modelType->equals(new ObjectType(Model::class))) {
-                return null;
-            }
-        }
-
         if ($modelType instanceof TypeWithClassName) {
             $modelReflection = $modelType->getClassReflection();
         } else {

src/Methods/RelationForwardsCallsExtension.php

@@ -6,7 +6,6 @@
 
 use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Database\Eloquent\Model;
-use Illuminate\Database\Eloquent\Relations\BelongsTo;
 use Illuminate\Database\Eloquent\Relations\Relation;
 use NunoMaduro\Larastan\Reflection\EloquentBuilderMethodReflection;
 use PHPStan\Reflection\ClassReflection;
@@ -109,14 +108,12 @@ private function findMethod(ClassReflection $classReflection, string $methodName
         $parametersAcceptor = ParametersAcceptorSelector::selectSingle($reflection->getVariants());
         $returnType = $parametersAcceptor->getReturnType();
 
-        $types = [$relatedModel];
-
-        // BelongsTo relation needs second generic type
-        if ((new ObjectType(BelongsTo::class))->isSuperTypeOf(new ObjectType($classReflection->getName()))->yes()) {
-            $childType = $classReflection->getActiveTemplateTypeMap()->getType('TChildModel');
-
-            if ($childType !== null) {
-                $types[] = $childType;
+        // Copy template parameters with generic types of relation
+        $types = [];
+        foreach (['TRelatedModel', 'TDeclaringModel', 'TIntermediateModel', 'TResult'] as $templateParameter) {
+            $type = $classReflection->getActiveTemplateTypeMap()->getType($templateParameter);
+            if ($type !== null) {
+                $types[] = $type;
             }
         }
 

src/ReturnTypes/BuilderModelFindExtension.php

@@ -59,9 +59,13 @@ public function isMethodSupported(MethodReflection $methodReflection): bool
             return false;
         }
 
-        $model = $methodReflection->getDeclaringClass()->getActiveTemplateTypeMap()->getType('TModelClass');
+        $templateTypeMap = $methodReflection->getDeclaringClass()->getActiveTemplateTypeMap();
+        $model =
+            $templateTypeMap->getType('TModelClass') ??
+            $templateTypeMap->getType('TRelatedModel') ??
+            $templateTypeMap->getType('TDeclaringModel');
 
-        if ($model === null || ! $model instanceof ObjectType) {
+        if (! $model instanceof ObjectType) {
             return false;
         }
 
@@ -81,8 +85,12 @@ public function getTypeFromMethodCall(
         MethodCall $methodCall,
         Scope $scope
     ): Type {
+        $templateTypeMap = $methodReflection->getDeclaringClass()->getActiveTemplateTypeMap();
         /** @var ObjectType $model */
-        $model = $methodReflection->getDeclaringClass()->getActiveTemplateTypeMap()->getType('TModelClass');
+        $model =
+            $templateTypeMap->getType('TModelClass') ??
+            $templateTypeMap->getType('TRelatedModel') ??
+            $templateTypeMap->getType('TDeclaringModel');
         $returnType = $methodReflection->getVariants()[0]->getReturnType();
         $argType = $scope->getType($methodCall->getArgs()[0]->value);
 

src/ReturnTypes/EloquentBuilderExtension.php

@@ -57,8 +57,12 @@ public function isMethodSupported(MethodReflection $methodReflection): bool
         }
 
         $templateTypeMap = $methodReflection->getDeclaringClass()->getActiveTemplateTypeMap();
+        $model =
+            $templateTypeMap->getType('TModelClass') ??
+            $templateTypeMap->getType('TRelatedModel') ??
+            $templateTypeMap->getType('TDeclaringModel');
 
-        if (! $templateTypeMap->getType('TModelClass') instanceof ObjectType) {
+        if (! $model instanceof ObjectType) {
             return false;
         }
 
@@ -74,7 +78,10 @@ public function getTypeFromMethodCall(
         $templateTypeMap = $methodReflection->getDeclaringClass()->getActiveTemplateTypeMap();
 
         /** @var Type|ObjectType|TemplateMixedType $modelType */
-        $modelType = $templateTypeMap->getType('TModelClass');
+        $modelType =
+            $templateTypeMap->getType('TModelClass') ??
+            $templateTypeMap->getType('TRelatedModel') ??
+            $templateTypeMap->getType('TDeclaringModel');
 
         if ($modelType instanceof ObjectType && in_array(Collection::class, $returnType->getReferencedClasses(), true)) {
             $collectionClassName = $this->builderHelper->determineCollectionClassName($modelType->getClassName());

src/Types/ModelRelationsDynamicMethodReturnTypeExtension.php

@@ -5,29 +5,37 @@
 namespace NunoMaduro\Larastan\Types;
 
 use Illuminate\Database\Eloquent\Model;
-use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\Relations\HasManyThrough;
 use Illuminate\Database\Eloquent\Relations\Relation;
 use NunoMaduro\Larastan\Concerns\HasContainer;
+use NunoMaduro\Larastan\Methods\BuilderHelper;
 use PhpParser\Node\Expr\MethodCall;
 use PHPStan\Analyser\Scope;
 use PHPStan\Reflection\MethodReflection;
 use PHPStan\Reflection\ParametersAcceptorSelector;
 use PHPStan\ShouldNotHappenException;
 use PHPStan\Type\DynamicMethodReturnTypeExtension;
 use PHPStan\Type\Generic\GenericObjectType;
+use PHPStan\Type\IntegerType;
 use PHPStan\Type\ObjectType;
 use PHPStan\Type\Type;
 
 class ModelRelationsDynamicMethodReturnTypeExtension implements DynamicMethodReturnTypeExtension
 {
     use HasContainer;
 
+    /** @var BuilderHelper */
+    private $builderHelper;
+
     /** @var RelationParserHelper */
     private $relationParserHelper;
 
-    public function __construct(RelationParserHelper $relationParserHelper)
-    {
+    public function __construct(
+        RelationParserHelper $relationParserHelper,
+        BuilderHelper $builderHelper
+    ) {
         $this->relationParserHelper = $relationParserHelper;
+        $this->builderHelper = $builderHelper;
     }
 
     public function getClass(): string
@@ -94,15 +102,38 @@ public function getTypeFromMethodCall(
             ->relationParserHelper
             ->findRelatedModelInRelationMethod($methodReflection);
 
-        $classReflection = $methodReflection->getDeclaringClass();
+        $declaringModelClassName = $methodReflection->getDeclaringClass()->getName();
+
+        $templateTypes = [
+            new ObjectType($relatedModelClassName),
+            new ObjectType($declaringModelClassName),
+        ];
+
+        $hasManyThroughType = new ObjectType(HasManyThrough::class);
+        if ($hasManyThroughType->isSuperTypeOf($returnType)->yes()) {
+            /** @var string $intermediateModelClassName */
+            $intermediateModelClassName = $this
+                ->relationParserHelper
+                ->findIntermediateModelInRelationMethod($methodReflection);
+            $templateTypes[] = new ObjectType($intermediateModelClassName);
+        }
 
-        if ($returnType->isInstanceOf(BelongsTo::class)->yes()) {
-            return new GenericObjectType($returnType->getClassName(), [
-                new ObjectType($relatedModelClassName),
-                new ObjectType($classReflection->getName()),
-            ]);
+        // Work-around for a Laravel bug
+        // Opposed to other `HasOne...` and `HasMany...` methods,
+        // `HasOneThrough` and `HasManyThrough` do not extend a common
+        // `HasOneOrManyThrough` base class, but `HasOneThrough` directly
+        // extends `HasManyThrough`.
+        // This does not only violate Liskov's Substitution Principle but also
+        // has the unfortunate side effect that `HasManyThrough` cannot
+        // bind the template parameter `TResult` to a Collection, but needs
+        // to keep it unbound for `HasOneThrough` to overwrite it.
+        // Hence, if `HasManyTrough` is used directly, we must bind the
+        // fourth template parameter `TResult` here.
+        if ($hasManyThroughType->equals($returnType)) {
+            $collectionClassName = $this->builderHelper->determineCollectionClassName($relatedModelClassName);
+            $templateTypes[] = new GenericObjectType($collectionClassName, [new IntegerType(), new ObjectType($relatedModelClassName)]);
         }
 
-        return new GenericObjectType($returnType->getClassName(), [new ObjectType($relatedModelClassName)]);
+        return new GenericObjectType($returnType->getClassName(), $templateTypes);
     }
 }

src/Types/RelationDynamicMethodReturnTypeExtension.php

@@ -5,8 +5,8 @@
 namespace NunoMaduro\Larastan\Types;
 
 use Illuminate\Database\Eloquent\Model;
-use Illuminate\Database\Eloquent\Relations\BelongsTo;
-use Illuminate\Database\Eloquent\Relations\MorphTo;
+use Illuminate\Database\Eloquent\Relations\HasManyThrough;
+use NunoMaduro\Larastan\Methods\BuilderHelper;
 use PhpParser\Node\Expr\MethodCall;
 use PHPStan\Analyser\Scope;
 use PHPStan\Reflection\FunctionVariant;
@@ -17,16 +17,19 @@
 use PHPStan\Type\Constant\ConstantStringType;
 use PHPStan\Type\DynamicMethodReturnTypeExtension;
 use PHPStan\Type\Generic\GenericObjectType;
+use PHPStan\Type\IntegerType;
 use PHPStan\Type\ObjectType;
-use PHPStan\Type\StaticType;
 use PHPStan\Type\Type;
+use PHPStan\Type\TypeWithClassName;
 
 class RelationDynamicMethodReturnTypeExtension implements DynamicMethodReturnTypeExtension
 {
+    private BuilderHelper $builderHelper;
     private ReflectionProvider $provider;
 
-    public function __construct(ReflectionProvider $provider)
+    public function __construct(BuilderHelper $builderHelper, ReflectionProvider $provider)
     {
+        $this->builderHelper = $builderHelper;
         $this->provider = $provider;
     }
 
@@ -53,6 +56,9 @@ public function getTypeFromMethodCall(
         MethodCall $methodCall,
         Scope $scope
     ): Type {
+        $methodName = $methodReflection->getName();
+        $methodArgs = $methodCall->getArgs();
+        $numArgs = count($methodArgs);
         /** @var FunctionVariant $functionVariant */
         $functionVariant = ParametersAcceptorSelector::selectSingle($methodReflection->getVariants());
         $returnType = $functionVariant->getReturnType();
@@ -61,38 +67,65 @@ public function getTypeFromMethodCall(
             return $returnType;
         }
 
-        $calledOnType = $scope->getType($methodCall->var);
-
-        if ($calledOnType instanceof StaticType) {
-            $calledOnType = new ObjectType($calledOnType->getClassName());
-        }
-
-        if (count($methodCall->getArgs()) === 0) {
+        if (
             // Special case for MorphTo. `morphTo` can be called without arguments.
-            if ($methodReflection->getName() === 'morphTo') {
-                return new GenericObjectType($returnType->getClassName(), [new ObjectType(Model::class), $calledOnType]);
-            }
-
+            ($methodName !== 'morphTo' && $numArgs < 1) ||
+            // Special case for "...Through". `has...Through` must be called with a 2nd parameter for the intermediate model
+            (in_array($methodName, ['hasOneThrough', 'hasManyThrough']) && $numArgs < 2)
+        ) {
             return $returnType;
         }
 
-        $argType = $scope->getType($methodCall->getArgs()[0]->value);
+        $templateTypes = [];
 
-        if (! $argType instanceof ConstantStringType) {
+        // Determine TRelatedModel; this is the 1st parameter, if given, or `Eloquent\Model`
+        $relatedModelClassArgType = $numArgs === 0 ?
+            new ConstantStringType(Model::class, true) :
+            $scope->getType($methodCall->getArgs()[0]->value);
+        if (! $relatedModelClassArgType instanceof ConstantStringType) {
             return $returnType;
         }
+        $relatedModelClassName = $relatedModelClassArgType->getValue();
+        if (! $this->provider->hasClass($relatedModelClassName)) {
+            $relatedModelClassName = Model::class;
+        }
+        $templateTypes[] = new ObjectType($relatedModelClassName);
 
-        $argClassName = $argType->getValue();
-
-        if (! $this->provider->hasClass($argClassName)) {
-            $argClassName = Model::class;
+        // Determine TDeclaringModel; this is the model on whose instance the method is called
+        $calledOnType = $scope->getType($methodCall->var);
+        if (! $calledOnType instanceof TypeWithClassName) {
+            return $returnType;
+        }
+        $declaringModelClassName = $calledOnType->getClassName();
+        $templateTypes[] = new ObjectType($declaringModelClassName);
+
+        // Determine TIntermediateModel for "Through" types; this is the 2nd parameter
+        $hasManyThroughType = new ObjectType(HasManyThrough::class);
+        if ($hasManyThroughType->isSuperTypeOf($returnType)->yes()) {
+            $intermediateModelClassArgType = $scope->getType($methodCall->getArgs()[1]->value);
+            if (! $intermediateModelClassArgType instanceof ConstantStringType) {
+                return $returnType;
+            }
+            $intermediateModelClassName = $intermediateModelClassArgType->getValue();
+            $templateTypes[] = new ObjectType($intermediateModelClassName);
         }
 
-        // Special case for BelongsTo. We need to add the child model as a generic type also.
-        if ((new ObjectType(BelongsTo::class))->isSuperTypeOf($returnType)->yes()) {
-            return new GenericObjectType($returnType->getClassName(), [new ObjectType($argClassName), $calledOnType]);
+        // Work-around for a Laravel bug
+        // Opposed to other `HasOne...` and `HasMany...` methods,
+        // `HasOneThrough` and `HasManyThrough` do not extend a common
+        // `HasOneOrManyThrough` base class, but `HasOneThrough` directly
+        // extends `HasManyThrough`.
+        // This does not only violate Liskov's Substitution Principle but also
+        // has the unfortunate side effect that `HasManyThrough` cannot
+        // bind the template parameter `TResult` to a Collection, but needs
+        // to keep it unbound for `HasOneThrough` to overwrite it.
+        // Hence, if `HasManyTrough` is used directly, we must bind the
+        // fourth template parameter `TResult` here.
+        if ($hasManyThroughType->equals($returnType)) {
+            $collectionClassName = $this->builderHelper->determineCollectionClassName($relatedModelClassName);
+            $templateTypes[] = new GenericObjectType($collectionClassName, [new IntegerType(), new ObjectType($relatedModelClassName)]);
         }
 
-        return new GenericObjectType($returnType->getClassName(), [new ObjectType($argClassName)]);
+        return new GenericObjectType($returnType->getClassName(), $templateTypes);
     }
 }