Resolve PHP version checks in return-type, throw-type and type-specifying extensions from Scope::getPhpVersion()

* Add the range-aware counterparts of the `PhpVersion` methods the extensions
  needed to `PhpVersions`: `arrayFunctionsReturnNullWithNonArray()`,
  `hasDateTimeExceptions()`, `hasFilterThrowOnFailureConstant()`,
  `hasPDOSubclasses()`, `hasStricterRoundFunctions()`,
  `highlightStringDoesNotReturnFalse()`, `strSplitReturnsEmptyArray()`,
  `substrReturnFalseInsteadOfEmptyString()`, `throwsOnInvalidMbStringEncoding()`,
  `supportsHhPrintfSpecifier()`, `supportsPassNoneEncodings()`,
  `supportsPregUnmatchedAsNull()`, `supportsPregCaptureOnlyNamedGroups()`,
  the three `mb_substitute_character` predicates and
  `supportsNativeReflectionAdapterReturnTypes()`.
* Add `PhpVersions::pickType()`, which returns the branch matching a certain
  version check and the union of both branches when the analysed version range
  spans them, so a `Maybe` answer never produces a type narrower than the truth.
* Convert every `Dynamic*ReturnTypeExtension`, `Dynamic*ThrowTypeExtension` and
  `*TypeSpecifyingExtension` in `src/Type/Php/` that injected `PhpVersion` (array
  functions, `substr`, `str_split`, `round`, `highlight_string`, `count_chars`,
  `hash`, `mb_*`, `min`/`max`, `openssl_cipher_*`, `printf`, `trigger_error`,
  `version_compare`, `filter_*`, `bcmath`, `PDO::connect`, the `DateTime`/
  `DateInterval`/`DateTimeZone` family) to read the version from the call's Scope.
* Thread `PhpVersions` through the helpers those extensions share:
  `ArrayColumnHelper`, `ArrayFilterFunctionReturnTypeHelper`,
  `FilterFunctionReturnTypeHelper`, `MbFunctionsReturnTypeExtensionTrait`,
  `PrintfFormatParser`, `RegexArrayShapeMatcher` and `RegexGroupParser`.
* `RegexArrayShapeMatcher` now folds the analysed version's
  `PREG_UNMATCHED_AS_NULL` support into the parsed flags, so
  `containsUnmatchedAsNull()` no longer needs a version of its own.
* `PDOConnectReturnTypeExtension` moved its version gate out of
  `isStaticMethodSupported()` (which gets no Scope) into
  `getTypeFromStaticMethodCall()`.
* The same treatment for the three BetterReflection adapter return-type
  extensions in `src/Reflection/`, and for `FilterVarRule` and the three
  `Printf*Rule`s that share the converted helpers.
* Add `PHPStan\Build\NoInjectedPhpVersionInScopeAwareExtensionRule` so extensions
  implementing a Scope-receiving interface cannot drift back to injecting
  `PhpVersion`. `OperatorTypeSpecifyingExtension` is deliberately not covered -
  its interface hands over no Scope, so `BcMathNumber*OperatorTypeSpecifyingExtension`
  keep their injected `PhpVersion`.

Author: staabm

build/PHPStan/Build/NoInjectedPhpVersionInScopeAwareExtensionRule.php

@@ -0,0 +1,91 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Build;
+
+use PhpParser\Node;
+use PHPStan\Analyser\Scope;
+use PHPStan\Node\InClassNode;
+use PHPStan\Php\PhpVersion;
+use PHPStan\Rules\Rule;
+use PHPStan\Rules\RuleErrorBuilder;
+use PHPStan\Type\DynamicFunctionReturnTypeExtension;
+use PHPStan\Type\DynamicFunctionThrowTypeExtension;
+use PHPStan\Type\DynamicMethodReturnTypeExtension;
+use PHPStan\Type\DynamicMethodThrowTypeExtension;
+use PHPStan\Type\DynamicStaticMethodReturnTypeExtension;
+use PHPStan\Type\DynamicStaticMethodThrowTypeExtension;
+use PHPStan\Type\FunctionTypeSpecifyingExtension;
+use PHPStan\Type\MethodTypeSpecifyingExtension;
+use PHPStan\Type\StaticMethodTypeSpecifyingExtension;
+use function sprintf;
+
+/**
+ * Every one of these extension interfaces hands the call's Scope to the extension,
+ * so the analysed PHP version must be read from Scope::getPhpVersion(). A DI-injected
+ * PhpVersion always answers with the configured version and silently ignores both
+ * PHP_VERSION_ID narrowing in the analysed code and configured version ranges.
+ *
+ * @implements Rule<InClassNode>
+ */
+final class NoInjectedPhpVersionInScopeAwareExtensionRule implements Rule
+{
+
+	private const SCOPE_AWARE_EXTENSIONS = [
+		DynamicFunctionReturnTypeExtension::class,
+		DynamicMethodReturnTypeExtension::class,
+		DynamicStaticMethodReturnTypeExtension::class,
+		DynamicFunctionThrowTypeExtension::class,
+		DynamicMethodThrowTypeExtension::class,
+		DynamicStaticMethodThrowTypeExtension::class,
+		FunctionTypeSpecifyingExtension::class,
+		MethodTypeSpecifyingExtension::class,
+		StaticMethodTypeSpecifyingExtension::class,
+	];
+
+	public function getNodeType(): string
+	{
+		return InClassNode::class;
+	}
+
+	public function processNode(Node $node, Scope $scope): array
+	{
+		$classReflection = $node->getClassReflection();
+		if (!$classReflection->hasConstructor()) {
+			return [];
+		}
+
+		$implementedExtension = null;
+		foreach (self::SCOPE_AWARE_EXTENSIONS as $extensionInterface) {
+			if (!$classReflection->is($extensionInterface)) {
+				continue;
+			}
+
+			$implementedExtension = $extensionInterface;
+			break;
+		}
+
+		if ($implementedExtension === null) {
+			return [];
+		}
+
+		$constructorVariant = $classReflection->getConstructor()->getOnlyVariant();
+		$errors = [];
+		foreach ($constructorVariant->getParameters() as $parameter) {
+			foreach ($parameter->getType()->getObjectClassNames() as $className) {
+				if ($className !== PhpVersion::class) {
+					continue;
+				}
+
+				$errors[] = RuleErrorBuilder::message(sprintf(
+					'%s implements %s and must not inject %s - read the analysed PHP version from Scope::getPhpVersion() instead.',
+					$classReflection->getDisplayName(),
+					$implementedExtension,
+					PhpVersion::class,
+				))->identifier('phpstanBuild.phpVersionInExtension')->build();
+			}
+		}
+
+		return $errors;
+	}
+
+}

build/phpstan.neon

@@ -201,6 +201,7 @@ parameters:
 rules:
 	- PHPStan\Build\FinalClassRule
 	- PHPStan\Build\NoScopeTypeReadInEngineRule
+	- PHPStan\Build\NoInjectedPhpVersionInScopeAwareExtensionRule
 	- PHPStan\Build\AttributeNamedArgumentsRule
 	- PHPStan\Build\NamedArgumentsRule
 	- PHPStan\Build\OverrideAttributeThirdPartyMethodRule

src/Php/PhpVersions.php

@@ -6,6 +6,7 @@
 use PHPStan\Turbo\ReferencedByTurboExtension;
 use PHPStan\Type\IntegerRangeType;
 use PHPStan\Type\Type;
+use PHPStan\Type\TypeCombinator;
 
 /**
  * Range-aware PHP version check that handles version uncertainty.
@@ -188,4 +189,120 @@ public function supportsDeprecatedTraits(): TrinaryLogic
 		return IntegerRangeType::fromInterval(80500, null)->isSuperTypeOf($this->phpVersions)->result;
 	}
 
+	public function arrayFunctionsReturnNullWithNonArray(): TrinaryLogic
+	{
+		return IntegerRangeType::fromInterval(null, 79999)->isSuperTypeOf($this->phpVersions)->result;
+	}
+
+	public function hasDateTimeExceptions(): TrinaryLogic
+	{
+		return IntegerRangeType::fromInterval(80300, null)->isSuperTypeOf($this->phpVersions)->result;
+	}
+
+	public function hasFilterThrowOnFailureConstant(): TrinaryLogic
+	{
+		return IntegerRangeType::fromInterval(80500, null)->isSuperTypeOf($this->phpVersions)->result;
+	}
+
+	public function hasPDOSubclasses(): TrinaryLogic
+	{
+		return IntegerRangeType::fromInterval(80400, null)->isSuperTypeOf($this->phpVersions)->result;
+	}
+
+	public function hasStricterRoundFunctions(): TrinaryLogic
+	{
+		return IntegerRangeType::fromInterval(80000, null)->isSuperTypeOf($this->phpVersions)->result;
+	}
+
+	public function highlightStringDoesNotReturnFalse(): TrinaryLogic
+	{
+		return IntegerRangeType::fromInterval(80400, null)->isSuperTypeOf($this->phpVersions)->result;
+	}
+
+	public function isEmptyStringValidAliasForNoneInMbSubstituteCharacter(): TrinaryLogic
+	{
+		return IntegerRangeType::fromInterval(null, 79999)->isSuperTypeOf($this->phpVersions)->result;
+	}
+
+	public function isNullValidArgInMbSubstituteCharacter(): TrinaryLogic
+	{
+		return IntegerRangeType::fromInterval(80000, null)->isSuperTypeOf($this->phpVersions)->result;
+	}
+
+	public function isNumericStringValidArgInMbSubstituteCharacter(): TrinaryLogic
+	{
+		return IntegerRangeType::fromInterval(null, 79999)->isSuperTypeOf($this->phpVersions)->result;
+	}
+
+	public function strSplitReturnsEmptyArray(): TrinaryLogic
+	{
+		return IntegerRangeType::fromInterval(80200, null)->isSuperTypeOf($this->phpVersions)->result;
+	}
+
+	public function substrReturnFalseInsteadOfEmptyString(): TrinaryLogic
+	{
+		return IntegerRangeType::fromInterval(null, 79999)->isSuperTypeOf($this->phpVersions)->result;
+	}
+
+	public function supportsAllUnicodeScalarCodePointsInMbSubstituteCharacter(): TrinaryLogic
+	{
+		return IntegerRangeType::fromInterval(70200, null)->isSuperTypeOf($this->phpVersions)->result;
+	}
+
+	public function supportsHhPrintfSpecifier(): TrinaryLogic
+	{
+		return IntegerRangeType::fromInterval(80000, null)->isSuperTypeOf($this->phpVersions)->result;
+	}
+
+	public function supportsPassNoneEncodings(): TrinaryLogic
+	{
+		return IntegerRangeType::fromInterval(null, 70299)->isSuperTypeOf($this->phpVersions)->result;
+	}
+
+	public function supportsPregCaptureOnlyNamedGroups(): TrinaryLogic
+	{
+		// https://php.watch/versions/8.2/preg-n-no-capture-modifier
+		return IntegerRangeType::fromInterval(80200, null)->isSuperTypeOf($this->phpVersions)->result;
+	}
+
+	public function supportsPregUnmatchedAsNull(): TrinaryLogic
+	{
+		// while PREG_UNMATCHED_AS_NULL is defined in php-src since 7.2.x it starts working as expected with 7.4.x
+		// https://3v4l.org/v3HE4
+		return IntegerRangeType::fromInterval(70400, null)->isSuperTypeOf($this->phpVersions)->result;
+	}
+
+	public function throwsOnInvalidMbStringEncoding(): TrinaryLogic
+	{
+		return IntegerRangeType::fromInterval(80000, null)->isSuperTypeOf($this->phpVersions)->result;
+	}
+
+	/**
+	 * PHPStan's BetterReflection adapters keep their narrowed native return types only on PHP 8+;
+	 * the downgraded PHP 7 build widens them back to the core Reflection ones.
+	 */
+	public function supportsNativeReflectionAdapterReturnTypes(): TrinaryLogic
+	{
+		return IntegerRangeType::fromInterval(80000, null)->isSuperTypeOf($this->phpVersions)->result;
+	}
+
+	/**
+	 * Resolves a version-dependent type.
+	 *
+	 * When the analysed PHP version range spans both sides of $versionCheck,
+	 * neither branch can be ruled out and the union of both is returned.
+	 */
+	public static function pickType(TrinaryLogic $versionCheck, Type $ifYes, Type $ifNo): Type
+	{
+		if ($versionCheck->yes()) {
+			return $ifYes;
+		}
+
+		if ($versionCheck->no()) {
+			return $ifNo;
+		}
+
+		return TypeCombinator::union($ifYes, $ifNo);
+	}
+
 }

src/Reflection/BetterReflection/Type/AdapterReflectionEnumCaseDynamicReturnTypeExtension.php

@@ -5,7 +5,6 @@
 use PhpParser\Node\Expr\MethodCall;
 use PHPStan\Analyser\Scope;
 use PHPStan\BetterReflection\Reflection\Adapter\ReflectionType;
-use PHPStan\Php\PhpVersion;
 use PHPStan\Reflection\MethodReflection;
 use PHPStan\Type\Constant\ConstantBooleanType;
 use PHPStan\Type\DynamicMethodReturnTypeExtension;
@@ -22,7 +21,7 @@ final class AdapterReflectionEnumCaseDynamicReturnTypeExtension implements Dynam
 	/**
 	 * @param class-string $class
 	 */
-	public function __construct(private PhpVersion $phpVersion, private string $class)
+	public function __construct(private string $class)
 	{
 	}
 
@@ -41,7 +40,7 @@ public function isMethodSupported(MethodReflection $methodReflection): bool
 
 	public function getTypeFromMethodCall(MethodReflection $methodReflection, MethodCall $methodCall, Scope $scope): ?Type
 	{
-		if ($this->phpVersion->getVersionId() >= 80000) {
+		if (!$scope->getPhpVersion()->supportsNativeReflectionAdapterReturnTypes()->no()) {
 			return null;
 		}
 

src/Reflection/BetterReflection/Type/AdapterReflectionEnumDynamicReturnTypeExtension.php

@@ -9,7 +9,6 @@
 use PHPStan\BetterReflection\Reflection\Adapter\ReflectionEnum;
 use PHPStan\BetterReflection\Reflection\Adapter\ReflectionNamedType;
 use PHPStan\DependencyInjection\AutowiredService;
-use PHPStan\Php\PhpVersion;
 use PHPStan\Reflection\MethodReflection;
 use PHPStan\Type\Accessory\AccessoryNonEmptyStringType;
 use PHPStan\Type\Constant\ConstantBooleanType;
@@ -27,10 +26,6 @@
 final class AdapterReflectionEnumDynamicReturnTypeExtension implements DynamicMethodReturnTypeExtension
 {
 
-	public function __construct(private PhpVersion $phpVersion)
-	{
-	}
-
 	public function getClass(): string
 	{
 		return ReflectionEnum::class;
@@ -52,7 +47,7 @@ public function isMethodSupported(MethodReflection $methodReflection): bool
 
 	public function getTypeFromMethodCall(MethodReflection $methodReflection, MethodCall $methodCall, Scope $scope): ?Type
 	{
-		if ($this->phpVersion->getVersionId() >= 80000) {
+		if (!$scope->getPhpVersion()->supportsNativeReflectionAdapterReturnTypes()->no()) {
 			return null;
 		}
 

src/Reflection/PHPStan/NativeReflectionEnumReturnDynamicReturnTypeExtension.php

@@ -5,7 +5,6 @@
 use PhpParser\Node\Expr\MethodCall;
 use PHPStan\Analyser\Scope;
 use PHPStan\BetterReflection\Reflection\Adapter\ReflectionClass;
-use PHPStan\Php\PhpVersion;
 use PHPStan\Reflection\MethodReflection;
 use PHPStan\Type\DynamicMethodReturnTypeExtension;
 use PHPStan\Type\ObjectType;
@@ -17,7 +16,7 @@ final class NativeReflectionEnumReturnDynamicReturnTypeExtension implements Dyna
 	/**
 	 * @param class-string $className
 	 */
-	public function __construct(private PhpVersion $phpVersion, private string $className, private string $methodName)
+	public function __construct(private string $className, private string $methodName)
 	{
 	}
 
@@ -33,7 +32,7 @@ public function isMethodSupported(MethodReflection $methodReflection): bool
 
 	public function getTypeFromMethodCall(MethodReflection $methodReflection, MethodCall $methodCall, Scope $scope): ?Type
 	{
-		if ($this->phpVersion->getVersionId() >= 80000) {
+		if (!$scope->getPhpVersion()->supportsNativeReflectionAdapterReturnTypes()->no()) {
 			return null;
 		}
 

src/Rules/Functions/FilterVarRule.php

@@ -7,7 +7,6 @@
 use PhpParser\Node\Name;
 use PHPStan\Analyser\Scope;
 use PHPStan\DependencyInjection\RegisteredRule;
-use PHPStan\Php\PhpVersion;
 use PHPStan\Reflection\ReflectionProvider;
 use PHPStan\Rules\Rule;
 use PHPStan\Rules\RuleErrorBuilder;
@@ -25,7 +24,6 @@ public function __construct(
 		private ReflectionProvider $reflectionProvider,
 		private FilterFunctionReturnTypeHelper $filterFunctionReturnTypeHelper,
 		private FilterFunctionFlagsHelper $filterFunctionFlagsHelper,
-		private PhpVersion $phpVersion,
 	)
 	{
 	}
@@ -51,7 +49,7 @@ public function processNode(Node $node, Scope $scope): array
 		}
 
 		if (
-			!$this->phpVersion->hasFilterThrowOnFailureConstant()
+			$scope->getPhpVersion()->hasFilterThrowOnFailureConstant()->no()
 			|| !$this->reflectionProvider->hasConstant(new Name\FullyQualified('FILTER_THROW_ON_FAILURE'), null)
 		) {
 			return [];

src/Rules/Functions/PrintfArrayParametersRule.php

@@ -67,7 +67,7 @@ public function processNode(Node $node, Scope $scope): array
 		foreach ($formatArgType->getConstantStrings() as $formatString) {
 			$format = $formatString->getValue();
 
-			$uses = $this->printfFormatParser->parse($format);
+			$uses = $this->printfFormatParser->parse($format, $scope->getPhpVersion());
 			if ($uses === null) {
 				return [
 					RuleErrorBuilder::message(sprintf(

src/Rules/Functions/PrintfParameterTypeRule.php

@@ -4,6 +4,7 @@
 
 use PhpParser\Node;
 use PHPStan\Analyser\Scope;
+use PHPStan\Php\PhpVersions;
 use PHPStan\Reflection\ReflectionProvider;
 use PHPStan\Rules\Rule;
 use PHPStan\Rules\RuleErrorBuilder;
@@ -94,7 +95,7 @@ public function processNode(Node $node, Scope $scope): array
 
 		$formatString = $formatArgTypeStrings[0];
 		$format = $formatString->getValue();
-		$placeholderMap = $this->getPlaceholders($format);
+		$placeholderMap = $this->getPlaceholders($format, $scope->getPhpVersion());
 		if ($placeholderMap === null) {
 			// Already reported by PrintfParametersRule.
 			return [];
@@ -176,9 +177,9 @@ public function processNode(Node $node, Scope $scope): array
 	/**
 	 * @return array<int, non-empty-list<PrintfPlaceholder>>|null parameter index => placeholders
 	 */
-	private function getPlaceholders(string $format): ?array
+	private function getPlaceholders(string $format, PhpVersions $phpVersions): ?array
 	{
-		$uses = $this->printfFormatParser->parse($format);
+		$uses = $this->printfFormatParser->parse($format, $phpVersions);
 		if ($uses === null) {
 			return null;
 		}