Use @var PHPDoc type for dynamicConstantNames instead of falling back to mixed

When a class constant has a @var PHPDoc type annotation and is listed in
dynamicConstantNames, use the PHPDoc type instead of generalizing the
literal value. This fixes the primary use case from phpstan/phpstan#9218
where `@var string|null` on a null-valued constant was ignored.

The fix adds a $phpDocType parameter to resolveClassConstantType() and
passes it from both call sites in InitializerExprTypeResolver. The
priority is: native type > PHPDoc type > generalized value > mixed.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: phpstan-bot

src/Analyser/ConstantResolver.php

@@ -435,7 +435,7 @@ public function resolveConstantType(string $constantName, Type $constantType): T
 		return $constantType;
 	}
 
-	public function resolveClassConstantType(string $className, string $constantName, Type $constantType, ?Type $nativeType): Type
+	public function resolveClassConstantType(string $className, string $constantName, Type $constantType, ?Type $nativeType, ?Type $phpDocType): Type
 	{
 		$lookupConstantName = sprintf('%s::%s', $className, $constantName);
 		if (array_key_exists($lookupConstantName, $this->dynamicConstantNames)) {
@@ -458,6 +458,10 @@ public function resolveClassConstantType(string $className, string $constantName
 				return $nativeType;
 			}
 
+			if ($phpDocType !== null) {
+				return $phpDocType;
+			}
+
 			if ($constantType->isConstantValue()->yes()) {
 				$generalized = $constantType->generalize(GeneralizePrecision::lessSpecific());
 				if ($generalized->isConstantValue()->yes()) {

src/Reflection/InitializerExprTypeResolver.php

@@ -2544,11 +2544,13 @@ function (Type $type, callable $traverse): Type {
 				if ($reflectionConstant->getType() !== null) {
 					$nativeType = TypehintHelper::decideTypeFromReflection($reflectionConstant->getType(), selfClass: $constantClassReflection);
 				}
+				$phpDocType = $constantClassReflection->getConstant($constantName)->getPhpDocType();
 				$types[] = $this->constantResolver->resolveClassConstantType(
 					$constantClassReflection->getName(),
 					$constantName,
 					$constantType,
 					$nativeType,
+					$phpDocType,
 				);
 				unset($this->currentlyResolvingClassConstant[$resolvingName]);
 				continue;
@@ -2577,6 +2579,7 @@ function (Type $type, callable $traverse): Type {
 				$constantName,
 				$constantType,
 				$nativeType,
+				$constantReflection->getPhpDocType(),
 			);
 			unset($this->currentlyResolvingClassConstant[$resolvingName]);
 			$types[] = $constantType;

tests/PHPStan/Analyser/data/dynamic-constant.php

@@ -18,6 +18,12 @@ class DynamicConstantClass
 	const DYNAMIC_TRUE_CONSTANT = true;
 	const DYNAMIC_FALSE_CONSTANT = false;
 	const DYNAMIC_EMPTY_ARRAY_CONSTANT = [];
+
+	/** @var string|null */
+	const DYNAMIC_NULL_WITH_PHPDOC_CONSTANT = null;
+
+	/** @var list<string> */
+	const DYNAMIC_EMPTY_ARRAY_WITH_PHPDOC_CONSTANT = [];
 }
 
 class NoDynamicConstantClass
@@ -45,5 +51,9 @@ private function rip()
 
 		// Empty array constant should generalize to mixed
 		assertType('mixed', DynamicConstantClass::DYNAMIC_EMPTY_ARRAY_CONSTANT);
+
+		// Bug 9218: dynamicConstantNames with @var PHPDoc type
+		assertType('string|null', DynamicConstantClass::DYNAMIC_NULL_WITH_PHPDOC_CONSTANT);
+		assertType('list<string>', DynamicConstantClass::DYNAMIC_EMPTY_ARRAY_WITH_PHPDOC_CONSTANT);
 	}
 }

tests/PHPStan/Analyser/dynamic-constants.neon

@@ -8,6 +8,8 @@ parameters:
 		- DynamicConstants\DynamicConstantClass::DYNAMIC_TRUE_CONSTANT
 		- DynamicConstants\DynamicConstantClass::DYNAMIC_FALSE_CONSTANT
 		- DynamicConstants\DynamicConstantClass::DYNAMIC_EMPTY_ARRAY_CONSTANT
+		- DynamicConstants\DynamicConstantClass::DYNAMIC_NULL_WITH_PHPDOC_CONSTANT
+		- DynamicConstants\DynamicConstantClass::DYNAMIC_EMPTY_ARRAY_WITH_PHPDOC_CONSTANT
 		- GLOBAL_DYNAMIC_CONSTANT
 		- GLOBAL_DYNAMIC_NULL_CONSTANT
 		DynamicConstants\DynamicConstantClass::DYNAMIC_CONSTANT_WITH_EXPLICIT_TYPES_IN_CLASS: 'string|null'