Add a dynamic return type extension for clamp()

src/Type/Php/ClampFunctionReturnTypeExtension.php

@@ -0,0 +1,66 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Type\Php;
+
+use PhpParser\Node\Expr\BinaryOp\Smaller;
+use PhpParser\Node\Expr\FuncCall;
+use PhpParser\Node\Expr\Ternary;
+use PHPStan\Analyser\Scope;
+use PHPStan\DependencyInjection\AutowiredService;
+use PHPStan\Node\Expr\AlwaysRememberedExpr;
+use PHPStan\Reflection\FunctionReflection;
+use PHPStan\Type\DynamicFunctionReturnTypeExtension;
+use PHPStan\Type\Type;
+use function count;
+
+#[AutowiredService]
+final class ClampFunctionReturnTypeExtension implements DynamicFunctionReturnTypeExtension
+{
+
+	public function isFunctionSupported(FunctionReflection $functionReflection): bool
+	{
+		return $functionReflection->getName() === 'clamp';
+	}
+
+	public function getTypeFromFunctionCall(FunctionReflection $functionReflection, FuncCall $functionCall, Scope $scope): ?Type
+	{
+		$args = $functionCall->getArgs();
+		if (count($args) !== 3) {
+			return null;
+		}
+
+		foreach ($args as $arg) {
+			if ($arg->unpack) {
+				return null;
+			}
+		}
+
+		$valueExpr = $args[0]->value;
+		$minExpr = $args[1]->value;
+		$maxExpr = $args[2]->value;
+		$valueType = $scope->getType($valueExpr);
+		$minType = $scope->getType($minExpr);
+		$maxType = $scope->getType($maxExpr);
+
+		// arrays are compared by size first, keep the native return type for them
+		if (!$valueType->isArray()->no() || !$minType->isArray()->no() || !$maxType->isArray()->no()) {
+			return null;
+		}
+
+		$value = new AlwaysRememberedExpr($valueExpr, $valueType, $scope->getNativeType($valueExpr));
+		$min = new AlwaysRememberedExpr($minExpr, $minType, $scope->getNativeType($minExpr));
+		$max = new AlwaysRememberedExpr($maxExpr, $maxType, $scope->getNativeType($maxExpr));
+
+		// same comparisons as php_math_clamp(): $max < $value ? $max : ($value < $min ? $min : $value)
+		return $scope->getType(new Ternary(
+			new Smaller($max, $value),
+			$max,
+			new Ternary(
+				new Smaller($value, $min),
+				$min,
+				$value,
+			),
+		));
+	}
+
+}

tests/PHPStan/Analyser/nsrt/clamp.php

@@ -0,0 +1,29 @@
+<?php // lint >= 8.6
+
+declare(strict_types = 1);
+
+namespace Clamp;
+
+use function PHPStan\Testing\assertType;
+
+/**
+ * @param int<0, 100> $percent
+ * @param int<-50, 50> $delta
+ * @param list<int> $list
+ */
+function doFoo(int $i, float $f, int|float $n, int $a, int $b, string $s, ?int $maybe, int $percent, int $delta, array $list): void
+{
+	assertType('int<1, 10>', clamp($i, 1, 10));
+	assertType('float', clamp($f, 1.0, 10.0));
+	assertType('1.0|10.0|int<1, 10>', clamp($i, 1.0, 10.0));
+	assertType('float|int<0, 1>', clamp($n, 0, 1));
+	assertType('int', clamp($i, $a, $b));
+	assertType('int<0, 100>', clamp($percent + $delta, 0, 100));
+	assertType('5', clamp(5, 1, 10));
+	assertType('10', clamp(15, 1, 10));
+	assertType('1', clamp(-3, 1, 10));
+	assertType('string', clamp($s, 'a', 'm'));
+	assertType('int<1, 10>', clamp($maybe, 1, 10));
+	assertType('int<1, 10>', clamp(max: 10, value: $i, min: 1));
+	assertType('mixed', clamp($list, [0], [10]));
+}