first pass

phpstan · shmax · Apr 1, 2026 · Apr 1, 2026 · Apr 1, 2026 · Apr 1, 2026
commit b973b5f5ddc0ec9d9ad45b3777b2903f7166b299
diff --git a/.idea/icon.png b/.idea/icon.png
diff --git a/composer.json b/composer.json
@@ -139,7 +139,10 @@
 				"patches/DependencyChecker.patch",
 				"patches/Resolver.patch"
 			],
-			"symfony/console": [
+			"phpstan/phpdoc-parser": [
+				"patches/phpdoc-parser-generic-type-aliases.patch"
+			],
+		"symfony/console": [
 				"patches/OutputFormatter.patch"
 			]
 		}

diff --git a/patches/phpdoc-parser-generic-type-aliases.patch b/patches/phpdoc-parser-generic-type-aliases.patch
diff --git a/src/PhpDoc/PhpDocNodeResolver.php b/src/PhpDoc/PhpDocNodeResolver.php
@@ -522,7 +522,7 @@ public function resolveTypeAliasTags(PhpDocNode $phpDocNode, NameScope $nameScop
 			foreach ($phpDocNode->getTypeAliasTagValues($tagName) as $typeAliasTagValue) {
 				$alias = $typeAliasTagValue->alias;
 				$typeNode = $typeAliasTagValue->type;
-				$resolved[$alias] = new TypeAliasTag($alias, $typeNode, $nameScope);
+				$resolved[$alias] = new TypeAliasTag($alias, $typeNode, $nameScope, $typeAliasTagValue->templateTypes);
 			}
 		}
 

diff --git a/src/PhpDoc/Tag/TypeAliasTag.php b/src/PhpDoc/Tag/TypeAliasTag.php
@@ -3,6 +3,7 @@
 namespace PHPStan\PhpDoc\Tag;
 
 use PHPStan\Analyser\NameScope;
+use PHPStan\PhpDocParser\Ast\PhpDoc\TemplateTagValueNode;
 use PHPStan\PhpDocParser\Ast\Type\TypeNode;
 use PHPStan\Type\TypeAlias;
 
@@ -12,10 +13,14 @@
 final class TypeAliasTag
 {
 
+	/**
+	 * @param TemplateTagValueNode[] $templateTagValueNodes
+	 */
 	public function __construct(
 		private string $aliasName,
 		private TypeNode $typeNode,
 		private NameScope $nameScope,
+		private array $templateTagValueNodes = [],
 	)
 	{
 	}
@@ -30,6 +35,8 @@ public function getTypeAlias(): TypeAlias
 		return new TypeAlias(
 			$this->typeNode,
 			$this->nameScope,
+			$this->templateTagValueNodes,
+			$this->aliasName,
 		);
 	}
 

diff --git a/src/PhpDoc/TypeNodeResolver.php b/src/PhpDoc/TypeNodeResolver.php
@@ -104,6 +104,7 @@
 use PHPStan\Type\Type;
 use PHPStan\Type\TypeAliasResolver;
 use PHPStan\Type\TypeAliasResolverProvider;
+use PHPStan\Type\TypeAlias;
 use PHPStan\Type\TypeCombinator;
 use PHPStan\Type\TypeUtils;
 use PHPStan\Type\UnionType;
@@ -829,6 +830,13 @@ static function (string $variance): TemplateTypeVariance {
 			return new ErrorType();
 		}
 
+		// Check for a generic type alias (e.g. ProviderRequest<AppraisalFilter>) before
+		// falling through to class-based generic resolution.
+		$genericTypeAlias = $this->findGenericTypeAlias($typeNode->type->name, $nameScope);
+		if ($genericTypeAlias !== null) {
+			return $genericTypeAlias->resolveWithArgs($this, $genericTypes);
+		}
+
 		$mainType = $this->resolveIdentifierTypeNode($typeNode->type, $nameScope);
 		$mainTypeObjectClassNames = $mainType->getObjectClassNames();
 		if (count($mainTypeObjectClassNames) > 1) {
@@ -1361,4 +1369,28 @@ private function getTypeAliasResolver(): TypeAliasResolver
 		return $this->typeAliasResolverProvider->getTypeAliasResolver();
 	}
 
+	/**
+	 * Returns the TypeAlias for $name if it is a generic (parameterised) type alias
+	 * visible in the current $nameScope, or null otherwise.
+	 */
+	private function findGenericTypeAlias(string $name, NameScope $nameScope): ?TypeAlias
+	{
+		if ($nameScope->shouldBypassTypeAliases()) {
+			return null;
+		}
+
+		$className = $nameScope->getClassNameForTypeAlias();
+		if ($className === null || !$this->getReflectionProvider()->hasClass($className)) {
+			return null;
+		}
+
+		$typeAliases = $this->getReflectionProvider()->getClass($className)->getTypeAliases();
+		if (!array_key_exists($name, $typeAliases)) {
+			return null;
+		}
+
+		$typeAlias = $typeAliases[$name];
+		return $typeAlias->isGeneric() ? $typeAlias : null;
+	}
+
 }
diff --git a/src/Type/Generic/TemplateTypeScope.php b/src/Type/Generic/TemplateTypeScope.php
@@ -12,6 +12,11 @@ public static function createWithAnonymousFunction(): self
 		return new self(null, null);
 	}
 
+	public static function createWithTypeAlias(string $className, string $aliasName): self
+	{
+		return new self($className, '__typeAlias_' . $aliasName);
+	}
+
 	public static function createWithFunction(string $functionName): self
 	{
 		return new self(null, $functionName);

diff --git a/src/Type/TypeAlias.php b/src/Type/TypeAlias.php
@@ -3,18 +3,34 @@
 namespace PHPStan\Type;
 
 use PHPStan\Analyser\NameScope;
+use PHPStan\PhpDoc\Tag\TemplateTag;
 use PHPStan\PhpDoc\TypeNodeResolver;
+use PHPStan\PhpDocParser\Ast\PhpDoc\TemplateTagValueNode;
 use PHPStan\PhpDocParser\Ast\Type\IdentifierTypeNode;
 use PHPStan\PhpDocParser\Ast\Type\TypeNode;
+use PHPStan\Type\Generic\TemplateTypeFactory;
+use PHPStan\Type\Generic\TemplateTypeHelper;
+use PHPStan\Type\Generic\TemplateTypeMap;
+use PHPStan\Type\Generic\TemplateTypeScope;
+use PHPStan\Type\Generic\TemplateTypeVariance;
+use PHPStan\Type\Generic\TemplateTypeVarianceMap;
+use function array_map;
+use function array_values;
+use function count;
 
 final class TypeAlias
 {
 
 	private ?Type $resolvedType = null;
 
+	/**
+	 * @param TemplateTagValueNode[] $templateTagValueNodes
+	 */
 	public function __construct(
 		private TypeNode $typeNode,
 		private NameScope $nameScope,
+		private array $templateTagValueNodes = [],
+		private string $aliasName = '',
 	)
 	{
 	}
@@ -26,12 +42,107 @@ public static function invalid(): self
 		return $self;
 	}
 
+	/**
+	 * Returns the type with TemplateType placeholders for any declared template params.
+	 * For non-generic aliases this is the fully-resolved concrete type.
+	 */
 	public function resolve(TypeNodeResolver $typeNodeResolver): Type
 	{
-		return $this->resolvedType ??= $typeNodeResolver->resolve(
-			$this->typeNode,
-			$this->nameScope,
+		if ($this->resolvedType !== null) {
+			return $this->resolvedType;
+		}
+
+		$nameScope = $this->nameScope;
+
+		if (count($this->templateTagValueNodes) > 0) {
+			$nameScope = $this->buildNameScopeWithTemplates($typeNodeResolver, $nameScope);
+		}
+
+		return $this->resolvedType = $typeNodeResolver->resolve($this->typeNode, $nameScope);
+	}
+
+	/** Whether this alias was declared with type parameters (e.g. @phpstan-type Foo<T>). */
+	public function isGeneric(): bool
+	{
+		return count($this->templateTagValueNodes) > 0;
+	}
+
+	/**
+	 * @return TemplateTagValueNode[]
+	 */
+	public function getTemplateTagValueNodes(): array
+	{
+		return $this->templateTagValueNodes;
+	}
+
+	/**
+	 * Resolves the alias body substituting concrete $args for each declared template parameter.
+	 *
+	 * @param Type[] $args Concrete types in the same order as the declared template params.
+	 */
+	public function resolveWithArgs(TypeNodeResolver $typeNodeResolver, array $args): Type
+	{
+		$resolvedType = $this->resolve($typeNodeResolver);
+
+		if (count($this->templateTagValueNodes) === 0) {
+			return $resolvedType;
+		}
+
+		// Map each template param name to the supplied arg (or its declared default / upper bound).
+		$templateTypeMapTypes = [];
+		foreach (array_values($this->templateTagValueNodes) as $i => $templateTagValueNode) {
+			if (isset($args[$i])) {
+				$templateTypeMapTypes[$templateTagValueNode->name] = $args[$i];
+			} else {
+				$bound = $templateTagValueNode->bound !== null
+					? $typeNodeResolver->resolve($templateTagValueNode->bound, $this->nameScope)
+					: new MixedType(true);
+				$default = $templateTagValueNode->default !== null
+					? $typeNodeResolver->resolve($templateTagValueNode->default, $this->nameScope)
+					: null;
+				$templateTypeMapTypes[$templateTagValueNode->name] = $default ?? $bound;
+			}
+		}
+
+		return TemplateTypeHelper::resolveTemplateTypes(
+			$resolvedType,
+			new TemplateTypeMap($templateTypeMapTypes),
+			TemplateTypeVarianceMap::createEmpty(),
+			TemplateTypeVariance::createInvariant(),
 		);
 	}
 
+	/**
+	 * Builds a NameScope augmented with TemplateType placeholders for each declared template param,
+	 * so the alias body can reference them (e.g. `TFilter` resolves to a TemplateType).
+	 */
+	private function buildNameScopeWithTemplates(TypeNodeResolver $typeNodeResolver, NameScope $nameScope): NameScope
+	{
+		$templateTags = [];
+		foreach ($this->templateTagValueNodes as $templateTagValueNode) {
+			$templateTags[$templateTagValueNode->name] = new TemplateTag(
+				$templateTagValueNode->name,
+				$templateTagValueNode->bound !== null
+					? $typeNodeResolver->resolve($templateTagValueNode->bound, $nameScope)
+					: new MixedType(true),
+				$templateTagValueNode->default !== null
+					? $typeNodeResolver->resolve($templateTagValueNode->default, $nameScope)
+					: null,
+				TemplateTypeVariance::createInvariant(),
+			);
+		}
+
+		$className = $nameScope->getClassNameForTypeAlias();
+		$templateTypeScope = ($className !== null && $this->aliasName !== '')
+			? TemplateTypeScope::createWithTypeAlias($className, $this->aliasName)
+			: TemplateTypeScope::createWithAnonymousFunction();
+
+		$templateTypeMap = new TemplateTypeMap(array_map(
+			static fn (TemplateTag $tag): Type => TemplateTypeFactory::fromTemplateTag($templateTypeScope, $tag),
+			$templateTags,
+		));
+
+		return $nameScope->withTemplateTypeMap($templateTypeMap, $templateTags);
+	}
+
 }