Add polyfill for PHP 8.6's clamp() function

[Soean]

PHP 8.6 introduces a new built-in clamp() function (​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 ​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

This pull request adds a polyfill for the new PHP 8.6 clamp() function to ensure compatibility with older PHP versions. It also introduces a helper function to throw the appropriate error type depending on the PHP version.

New function polyfills and helpers:

• Added _wp_throw_value_error() to throw a ValueError on PHP 8.0+ or an InvalidArgumentException on PHP 7.x, providing consistent error handling for polyfills.
• Added a polyfill for the clamp() function, which restricts a value within a specified minimum and maximum, including input validation and appropriate error throwing for invalid arguments.

Trac ticket: https://core.trac.wordpress.org/ticket/65143

## Use of AI Tools

AI assistance: Yes
Tool(s): GitHub Copilot
Model(s): Claude Opus 4.6
Used for: Code docs.

[Soean]

This is the correct RFC: ​https://wiki.php.net/rfc/clamp_v2

[westonruter]

Are there places where clamp() should be used in core? I think generally a polyfill would be added if it is actually used.

[Soean]

@westonruter I added two places to the PR, where we can use it in Core.

Providing a polyfill in WordPress Core ensures that plugin and theme developers can use it consistently across all supported PHP versions without needing to implement their own.

[westonruter]

Great. Let's get this in the queue for 7.1.