[RFC] [Discussion] Add clamp function

Hi

Am 2025-08-28 08:35, schrieb Hans Krentel:

This also highlights a minor but important clarification for the
documentation. To make the behavior perfectly unambiguous, I suggest
a small edit to explicitly state the bounds are inclusive.

This is a good point and I agree that it should be spelled out
explicitly. However to me this also raises the question if the interval
boundaries should be configurable to switch between closed intervals and
(half-)open intervals. For many applications of continuous values a
right-open interval (excluding the upper boundary) is more useful, since
this makes it easy to generate non-overlapping ranges (e.g. to clamp to
a given day when passing DateTimeImmutable). This would also provide an
additional value-add over the min-max construction, where the boundaries
would need to be calculated manually, which is super complicated to do
in userland for floats.

There's precedent in ext/random with the Randomizer::getFloat() method
that takes a Random\IntervalBoundary enum to decide on the the
interpretation of the boundary values. Translated to clamp() this
could mean:

 $value = 1.0;
 clamp($value, 0.0, 1.0, IntervalBoundary::ClosedOpen); // 

0.999999999999999888978

Best regards
Tim Düsterhus

Thanks Larry!

Hey,

Hello,

I handled the feedback received on the draft RCF https://wiki.php.net/rfc/clamp_v2

If I didn't forget anything this should be now ready for discussion. So I updated its status.

There is an implementation proposal: https://github.com/php/php-src/pull/19434
And some draft for documentation here: https://github.com/php/doc-en/pull/4814

Thanks,

As others have noted before, what's the motivation of having the
to-be-clamped value as first parameter rather than infixed between min
and max?

E.g. from CSS: https://developer.mozilla.org/en-US/docs/Web/CSS/clamp:

clamp(min, val, max)

Feels to me as the most natural order, too.

You mention it was taken from the first RFC, but that one also did not
discuss the ordering in the first place either.
Some quick data points from momentary googling:

CSS: clamp(min, val, max)

Python: clamp(val, min, max)
C++: clamp(val, min, max)
Java: clamp(val, in, max)
Javascript: clamp(val, min, max)
C#: clamp(val, min, max)

Kotlin: val.clamp(min, max) (as an extension function)
Ruby: val.clamp(min, max)

So it looks like CSS is the oddball here. We should follow the clear majority approach. (Kyle, feel free to include this in the RFC.)

--Larry Garfield

Indeed, that makes sense then. I must admit that I've only ever been
using the clamp from CSS, but never from other languages. (I still think
value in the middle makes more sense, but I guess that's me then, and I
won't object.)

Then yes, please note it in the RFC :-)

Bob

On Wed, Aug 27, 2025, 12:44 PM Larry Garfield larry@garfieldtech.com
wrote:

Hey,

Hello,

I handled the feedback received on the draft RCF
https://wiki.php.net/rfc/clamp_v2

If I didn't forget anything this should be now ready for discussion. So
I updated its status.

There is an implementation proposal:
https://github.com/php/php-src/pull/19434
And some draft for documentation here:
https://github.com/php/doc-en/pull/4814

Thanks,

As others have noted before, what's the motivation of having the
to-be-clamped value as first parameter rather than infixed between min
and max?

E.g. from CSS: https://developer.mozilla.org/en-US/docs/Web/CSS/clamp:

clamp(min, val, max)

Feels to me as the most natural order, too.

You mention it was taken from the first RFC, but that one also did not
discuss the ordering in the first place either.

Some quick data points from momentary googling:

CSS: clamp(min, val, max)

Python: clamp(val, min, max)
C++: clamp(val, min, max)
Java: clamp(val, in, max)
Javascript: clamp(val, min, max)
C#: clamp(val, min, max)

Kotlin: val.clamp(min, max) (as an extension function)
Ruby: val.clamp(min, max)

So it looks like CSS is the oddball here. We should follow the clear
majority approach. (Kyle, feel free to include this in the RFC.)

--Larry Garfield

A reference from userland, Laravel has Number::clamp($val, $min, $max) as
well.

https://github.com/laravel/framework/blob/12.x/src%2FIlluminate%2FSupport%2FNumber.php#L301

...So it looks like CSS is the oddball here. We should follow the clear
majority approach...

While the majority of languages favor clamp($value, $min, $max),
dismissing the CSS order without examining the "why" misses a valuable
perspective, especially for a language so intertwined with web development.

The rationale for aligning with the majority (and the current RFC) boils
down to the Principle of Least Surprise within PHP's own ecosystem.

PHP is an imperative language. Its standard library functions,
particularly in math, consistently take the value to be operated on as
the first argument: min($value1, $value2), max($value1, $value2),
round($value, $precision). Introducing clamp($min, $value, $max)
would break this pattern, making it the odd one out within PHP itself.
This internal inconsistency would be a greater source of errors for PHP
developers than not matching an external standard like CSS.

The solution to the CSS dissonance is not to change the function but to
document it explicitly:

Note for Web Developers: This function uses the argument order
clamp(value, min, max), which differs from the CSS function
clamp(min, value, max).

This addresses the concern head-on. The ultimate win is not the argument
order itself, but the mere existence of the function, which finally
banishes the awkward and error-prone max($min, min($max, $value))
incantation.

My 2cents,
--hakre