Generics on phpstan-type aliases

composer.json

@@ -112,6 +112,10 @@
 			"symfony/console": [
 				"patches/OutputFormatter.patch",
 				"patches/Application.patch"
+			],
+			"phpstan/phpdoc-parser": [
+				"patches/TypeAliasTagValueNode.patch",
+				"patches/PhpDocParser.patch"
 			]
 		}
 	},

patches/PhpDocParser.patch

@@ -0,0 +1,39 @@
+--- src/Parser/PhpDocParser.php
++++ src/Parser/PhpDocParser.php
+@@ -1067,6 +1067,21 @@
+ 		$alias = $tokens->currentTokenValue();
+ 		$tokens->consumeTokenType(Lexer::TOKEN_IDENTIFIER);
+
++		$templateTypes = [];
++		if ($tokens->tryConsumeTokenType(Lexer::TOKEN_OPEN_ANGLE_BRACKET)) {
++			do {
++				$startLine = $tokens->currentTokenLine();
++				$startIndex = $tokens->currentTokenIndex();
++				$templateTypes[] = $this->enrichWithAttributes(
++					$tokens,
++					$this->typeParser->parseTemplateTagValue($tokens),
++					$startLine,
++					$startIndex,
++				);
++			} while ($tokens->tryConsumeTokenType(Lexer::TOKEN_COMMA));
++			$tokens->consumeTokenType(Lexer::TOKEN_CLOSE_ANGLE_BRACKET);
++		}
++
+ 		// support phan-type/psalm-type syntax
+ 		$tokens->tryConsumeTokenType(Lexer::TOKEN_EQUAL);
+
+@@ -1087,12 +1102,13 @@
+ 				}
+ 			}
+
+-			return new Ast\PhpDoc\TypeAliasTagValueNode($alias, $type);
++			return new Ast\PhpDoc\TypeAliasTagValueNode($alias, $type, $templateTypes);
+ 		} catch (ParserException $e) {
+ 			$this->parseOptionalDescription($tokens, false);
+ 			return new Ast\PhpDoc\TypeAliasTagValueNode(
+ 				$alias,
+ 				$this->enrichWithAttributes($tokens, new Ast\Type\InvalidTypeNode($e), $startLine, $startIndex),
++				$templateTypes,
+ 			);
+ 		}
+ 	}

patches/TypeAliasTagValueNode.patch

@@ -0,0 +1,47 @@
+--- src/Ast/PhpDoc/TypeAliasTagValueNode.php
++++ src/Ast/PhpDoc/TypeAliasTagValueNode.php
+@@ -4,6 +4,7 @@
+
+ use PHPStan\PhpDocParser\Ast\NodeAttributes;
+ use PHPStan\PhpDocParser\Ast\Type\TypeNode;
++use function implode;
+ use function trim;
+
+ class TypeAliasTagValueNode implements PhpDocTagValueNode
+@@ -15,15 +16,25 @@
+
+ 	public TypeNode $type;
+
+-	public function __construct(string $alias, TypeNode $type)
++	/** @var TemplateTagValueNode[] */
++	public array $templateTypes;
++
++	/**
++	 * @param TemplateTagValueNode[] $templateTypes
++	 */
++	public function __construct(string $alias, TypeNode $type, array $templateTypes = [])
+ 	{
+ 		$this->alias = $alias;
+ 		$this->type = $type;
++		$this->templateTypes = $templateTypes;
+ 	}
+
+ 	public function __toString(): string
+ 	{
+-		return trim("{$this->alias} {$this->type}");
++		$templateTypes = $this->templateTypes !== []
++			? '<' . implode(', ', $this->templateTypes) . '>'
++			: '';
++		return trim("{$this->alias}{$templateTypes} {$this->type}");
+ 	}
+
+ 	/**
+@@ -31,7 +42,7 @@
+ 	 */
+ 	public static function __set_state(array $properties): self
+ 	{
+-		$instance = new self($properties['alias'], $properties['type']);
++		$instance = new self($properties['alias'], $properties['type'], $properties['templateTypes'] ?? []);
+ 		if (isset($properties['attributes'])) {
+ 			foreach ($properties['attributes'] as $key => $value) {
+ 				$instance->setAttribute($key, $value);

src/PhpDoc/PhpDocNodeResolver.php

@@ -554,7 +554,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);
 			}
 		}
 

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,
 		);
 	}
 

src/PhpDoc/TypeNodeResolver.php

@@ -110,6 +110,7 @@
 use PHPStan\Type\StringType;
 use PHPStan\Type\ThisType;
 use PHPStan\Type\Type;
+use PHPStan\Type\TypeAlias;
 use PHPStan\Type\TypeAliasResolver;
 use PHPStan\Type\TypeAliasResolverProvider;
 use PHPStan\Type\TypeCombinator;
@@ -119,6 +120,7 @@
 use PHPStan\Type\ValueOfType;
 use PHPStan\Type\VoidType;
 use Traversable;
+use function array_filter;
 use function array_key_exists;
 use function array_map;
 use function array_values;
@@ -873,6 +875,23 @@ static function (string $variance): TemplateTypeVariance {
 			return new ErrorType();
 		}
 
+		// Check for a generic type alias (e.g. MyList<string>) before falling through to
+		// class-based generic resolution.
+		$genericTypeAlias = $typeNode->type instanceof IdentifierTypeNode ? $this->findGenericTypeAlias($typeNode->type->name, $nameScope) : null;
+		if ($genericTypeAlias !== null) {
+			$templateNodes = $genericTypeAlias->getTemplateTagValueNodes();
+			$totalParams = count($templateNodes);
+			$requiredParams = count(array_filter($templateNodes, static fn ($tvn) => $tvn->default === null));
+			$providedArgs = count($genericTypes);
+
+			if ($providedArgs > $totalParams || $providedArgs < $requiredParams) {
+				return new ErrorType();
+			}
+
+			$appType = $genericTypeAlias->createApplicationType($this, $genericTypes);
+			return $appType->isResolvable() ? $appType->resolve() : $appType;
+		}
+
 		$mainType = $typeNode->type instanceof NameNode
 			? $this->resolveNameNode($typeNode->type, $nameScope)
 			: $this->resolveIdentifierTypeNode($typeNode->type, $nameScope);
@@ -1524,4 +1543,39 @@ 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;
+		}
+
+		// Fast path: if the name isn't registered as a type alias in this scope, skip the
+		// more expensive ClassReflection::getTypeAliases() call. This also prevents a circular
+		// NameScope-building issue: getTypeAliases() can trigger FileTypeMapper::getResolvedPhpDoc()
+		// which calls getNameScope() — if we are already inside getNameScope() for this class,
+		// that throws NameScopeAlreadyBeingCreatedException, causing the class's ResolvedPhpDocBlock
+		// to be poisoned with an empty block and all its type aliases to be lost.
+		// UsefulTypeAliasResolver uses the same guard.
+		if (!$nameScope->hasTypeAlias($name)) {
+			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;
+	}
+
 }

src/Rules/MissingTypehintCheck.php

@@ -19,6 +19,7 @@
 use PHPStan\Type\Generic\GenericStaticType;
 use PHPStan\Type\Generic\TemplateType;
 use PHPStan\Type\Generic\TemplateTypeHelper;
+use PHPStan\Type\GenericTypeAliasType;
 use PHPStan\Type\IntersectionType;
 use PHPStan\Type\MixedType;
 use PHPStan\Type\ObjectType;
@@ -30,6 +31,7 @@
 use function array_filter;
 use function array_keys;
 use function array_merge;
+use function array_unique;
 use function array_values;
 use function count;
 use function implode;
@@ -159,6 +161,16 @@ public function getNonGenericObjectTypesWithGenericClass(Type $type): array
 			if ($type instanceof TemplateType) {
 				return $type;
 			}
+			if ($type instanceof GenericTypeAliasType) {
+				$missing = $type->getMissingRequiredParamNames();
+				if ($missing !== []) {
+					$objectTypes[] = [
+						sprintf('type alias %s', $type->getAliasName()),
+						implode(', ', array_unique($missing)),
+					];
+				}
+				return $traverse($type);
+			}
 			if ($type instanceof ObjectType) {
 				$classReflection = $type->getClassReflection();
 				if ($classReflection === null) {

src/Rules/PhpDoc/InvalidPhpDocVarTagTypeRule.php

@@ -121,6 +121,7 @@ public function processNode(Node $node, Scope $scope): array
 						->identifier('missingType.generics')
 						->build();
 				}
+
 			}
 
 			$escapedIdentifier = SprintfHelper::escapeFormatString($identifier);

src/Type/Generic/TemplateTypeScope.php

@@ -4,6 +4,9 @@
 
 use PHPStan\Turbo\ShadowedByTurboExtension;
 use function sprintf;
+use function str_starts_with;
+use function strlen;
+use function substr;
 
 #[ShadowedByTurboExtension(implementation: __DIR__ . '/../../../turbo-ext/src/TemplateTypeScope.cpp')]
 final class TemplateTypeScope
@@ -14,6 +17,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);
@@ -45,6 +53,22 @@ public function getFunctionName(): ?string
 		return $this->functionName;
 	}
 
+	/** @api */
+	public function isTypeAlias(): bool
+	{
+		return $this->functionName !== null && str_starts_with($this->functionName, '__typeAlias_');
+	}
+
+	/** @api */
+	public function getTypeAliasName(): ?string
+	{
+		if (!$this->isTypeAlias() || $this->functionName === null) {
+			return null;
+		}
+
+		return substr($this->functionName, strlen('__typeAlias_'));
+	}
+
 	/** @api */
 	public function equals(self $other): bool
 	{