[wp-trac] [WordPress Trac] #65143: Add polyfill for PHP 8.6's clamp() function

[WordPress Trac]

#65143: Add polyfill for PHP 8.6's clamp() function
-------------------------------+-----------------------------
 Reporter:  Soean              |      Owner:  (none)
     Type:  enhancement        |     Status:  new
 Priority:  normal             |  Milestone:  Awaiting Review
Component:  General            |    Version:
 Severity:  normal             |   Keywords:
  Focuses:  php-compatibility  |
-------------------------------+-----------------------------
 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

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/65143>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform