Implement clamp function

Co-authored-by: thinkverse <[email protected]>

Author: kylekatarnls

ext/standard/basic_functions.stub.php

@@ -1629,6 +1629,12 @@ function min(mixed $value, mixed ...$values): mixed {}
  */
 function max(mixed $value, mixed ...$values): mixed {}
 
+/**
+ * @compile-time-eval
+ * @frameless-function {"arity": 3}
+ */
+function clamp(mixed $value, mixed $min, mixed $max): mixed {}
+
 function array_walk(array|object &$array, callable $callback, mixed $arg = UNKNOWN): true {}
 
 function array_walk_recursive(array|object &$array, callable $callback, mixed $arg = UNKNOWN): true {}

ext/standard/basic_functions_arginfo.h

@@ -389,6 +389,59 @@ PHP_FUNCTION(round)
 }
 /* }}} */
 
+/* {{{ Return the given value if in range of min and max */
+PHP_FUNCTION(clamp)
+{
+	zval *zvalue, *zmin, *zmax;
+
+	ZEND_PARSE_PARAMETERS_START(3, 3)
+		Z_PARAM_ZVAL(zvalue)
+		Z_PARAM_ZVAL(zmin)
+		Z_PARAM_ZVAL(zmax)
+	ZEND_PARSE_PARAMETERS_END();
+
+	if (zend_compare(zmin, zmax) > 0) {
+		zend_argument_value_error(2, "must be smaller than or equal to argument #3 ($max)");
+		RETURN_THROWS();
+	}
+
+	if (zend_compare(zmax, zvalue) == -1) {
+		RETURN_COPY_VALUE(zmax);
+	}
+
+	if (zend_compare(zvalue, zmin) == -1) {
+		RETURN_COPY_VALUE(zmin);
+	}
+
+	RETURN_COPY_VALUE(zvalue);
+}
+/* }}} */
+
+/* {{{ Return the given value if in range of min and max */
+ZEND_FRAMELESS_FUNCTION(clamp, 3)
+{
+	zval *zvalue, *zmin, *zmax;
+	Z_FLF_PARAM_ZVAL(1, zvalue);
+	Z_FLF_PARAM_ZVAL(2, zmin);
+	Z_FLF_PARAM_ZVAL(3, zmax);
+
+	if (zend_compare(zmin, zmax) > 0) {
+		zend_argument_value_error(2, "must be smaller than or equal to argument #3 ($max)");
+		RETURN_THROWS();
+	}
+
+	if (zend_compare(zmax, zvalue) == -1) {
+		RETURN_COPY_VALUE(zmax);
+	}
+
+	if (zend_compare(zvalue, zmin) == -1) {
+		RETURN_COPY_VALUE(zmin);
+	}
+
+	RETURN_COPY_VALUE(zvalue);
+}
+/* }}} */
+
 /* {{{ Returns the sine of the number in radians */
 PHP_FUNCTION(sin)
 {

ext/standard/math.c

@@ -0,0 +1,35 @@
+--TEST--
+clamp() tests
+--INI--
+precision=14
+date.timezone = UTC
+--FILE--
+<?php
+
+var_dump(clamp(2, 1, 3));
+var_dump(clamp(0, 1, 3));
+var_dump(clamp(6, 1, 3));
+var_dump(clamp(2, 1.3, 3.4));
+var_dump(clamp(2.5, 1, 3));
+var_dump(clamp(2.5, 1.3, 3.4));
+var_dump(clamp(0, 1.3, 3.4));
+var_dump(clamp(M_PI, -INF, INF));
+var_dump(clamp("a", "c", "g"));
+var_dump(clamp("d", "c", "g"));
+echo clamp('2025-08-01', '2025-08-15', '2025-09-15'), "\n";
+echo clamp('2025-08-20', '2025-08-15', '2025-09-15'), "\n";
+
+?>
+--EXPECT--
+int(2)
+int(1)
+int(3)
+int(2)
+float(2.5)
+float(2.5)
+float(1.3)
+float(3.141592653589793)
+string(1) "c"
+string(1) "d"
+2025-08-15
+2025-08-20