id	summary	reporter	owner	description	type	status	priority	milestone	component	version	severity	resolution	keywords	cc	focuses
65143	Add polyfill for PHP 8.6's clamp() function	Soean	westonruter	"PHP 8.6 introduces a new built-in `clamp()` function ([https://wiki.php.net/rfc/clamp RFC]) that clamps a value within a given range. If the value is within bounds, it is returned as-is; otherwise, the nearest bound is returned.

Since WordPress supports PHP 7.4 and above a polyfill is needed so WordPress and plugins can safely use `clamp()` without checking the PHP version.

=== Proposed Behavior ===

 * If `$value` is within `[$min, $max]`, returns `$value`.
 * If `$value > $max`, returns `$max`.
 * If `$value < $min`, returns `$min`.
 * Throws `ValueError` (PHP >= 8.0) or `InvalidArgumentException` (PHP 7.x) if `$min > $max` or if `$min`/`$max` is `NAN`.

The polyfill relies on a new private helper `_wp_throw_value_error()`, which conditionally throws `ValueError` on PHP >= 8.0 and falls back to `InvalidArgumentException` on PHP 7.x — consistent with how [https://github.com/symfony/polyfill-php86 Symfony] handles the same compatibility problem.

=== Usage Examples ===

{{{
clamp( 5, 0, 100 );   // 5
clamp( -5, 0, 100 );  // 0
clamp( 105, 0, 100 ); // 100

clamp( 3.14, 0, 20 );  // 3.14
clamp( 3.14, 10, 20 ); // 10

clamp( 'P', 'A', 'Z' ); // ""P""
clamp( 'P', 'X', 'Z' ); // ""X""

clamp( new DateTimeImmutable('2026-01-08'), new DateTimeImmutable('2026-01-01'), new DateTimeImmutable('2026-12-31') );
// DateTimeImmutable('2026-01-08')

clamp( 4, NAN, 6 ); // ValueError: clamp(): Argument #2 ($min) cannot be NAN
clamp( 4, 8, 6 );   // ValueError: clamp(): Argument #2 ($min) must be smaller than or equal to argument #3 ($max)
}}}

=== Changes ===

 * `src/wp-includes/compat.php`: Add `_wp_throw_value_error()` helper and `clamp()` polyfill.

=== References ===

 * PHP RFC: https://wiki.php.net/rfc/clamp
 * PHP implementation PR: https://github.com/php/php-src/pull/19434
 * Symfony polyfill reference: https://github.com/symfony/polyfill-php86"	enhancement	reviewing	normal	7.1	General		normal		has-patch		php-compatibility