[RFC] Add clamp function

[kylekatarnls]

Follow-up #7191

Implementation for the RFC: https://wiki.php.net/rfc/clamp_v2 (see also https://wiki.php.net/rfc/clamp)

clamp(2, min: 1, max: 3) // 2
clamp(0, min: 1, max: 3) // 1
clamp(6, min: 1, max: 3) // 3
clamp(2, 1.3, 3.4) // 2
clamp(2.5, 1, 3) // 2.5
clamp(2.5, 1.3, 3.4) // 2.5
clamp(0, 1.3, 3.4) // 1.3
clamp(M_PI, -INF, INF) // 3.141592653589793
clamp(NAN, 4, 6) // NAN
clamp("a", "c", "g") // "c"
clamp("d", "c", "g") // "d"
clamp(new \DateTimeImmutable('2025-08-01'), new \DateTimeImmutable('2025-08-15'), new \DateTimeImmutable('2025-09-15'))->format('Y-m-d') // 2025-08-15
clamp(new \DateTimeImmutable('2025-08-20'), new \DateTimeImmutable('2025-08-15'), new \DateTimeImmutable('2025-09-15'))->format('Y-m-d') // 2025-08-20

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

clamp(4, NAN, 6)
// Throws ValueError: clamp(): Argument #2 ($min) cannot be NAN

clamp(4, 6, NAN)
// Throws ValueError: clamp(): Argument #3 ($max) cannot be NAN

Documentation: php/doc-en#4814

[medabkari]

The RFC page status is set to Withdrawn, update it to Draft if you have access.

[kylekatarnls]

Hello @kocsismate and @bukka, any news about this proposal to reconsider clamp RFC?

[TimWolla]

@kylekatarnls RFCs are discussed on the mailing list and then need to be voted on. See https://wiki.php.net/rfc/howto for an explanation of the process.

[kylekatarnls]

Thanks. I'd like to participate there, but I failed to create a wiki account, the captcha stuff is asking me "To which email address do you have to send an email to now?" and re-reading the whole page, I tried [email protected] but it's not that, now, I've no idea what it's expecting from me. 😞 Life is hard for humans who failed the Turing test.

[TimWolla]

I tried [email protected] but it's not that, now, I've no idea what it's expecting from me. 😞

That is accurate:

https://github.com/php/web-wiki/blob/0fbb083c530dfa960a73c8cca82193fe4004f00e/dokuwiki/lib/plugins/phpreg/action.php#L87

What error message did you receive?

[kylekatarnls]

Thanks for pointing me to the source code of the wiki, my error was The user could not be created. which from source code can have multiple reasons, but mine was that I already have an account (probably created a decade ago 😄) All good now 👍

[ndossche]

Thanks for the changes. The only thing missing right now is testing the non-frameless version. Because you have a test file that only utilises the global namespace, it can use the frameless variant. So the code path from the non-frameless version isn't tested.

[kylekatarnls]

Hi thanks for the review, I was off and didn't check deep yet, I though it was a matter of opcache.enable=1 but it still does not sounds to use the non-frameless version when ran locally. If you know about any existing test for a function that also has both variant, I would take a look at it this week. 🙏

[ndossche]

@kylekatarnls I would do something like this: https://gist.github.com/ndossche/33f72df9907ecfd8b0493c7e50d4494a

The diff looks a bit messy, but the idea is to call clamp() twice and assert the result is the same: once we call it as an FLF, once dynamically via an FCC. For exceptions, we make a wrapper function that executes both variants with try-catch.

[kylekatarnls]

Thanks for the help @ndossche I verified both were used by giving them different behaviors, and confirm $flf = clamp($value, $min, $max); and $dyn = make_clamp_fcc()($value, $min, $max); take respectively ZEND_FRAMELESS_FUNCTION(clamp, 3) and PHP_FUNCTION(clamp) paths 👌

It's now covered.

[ndossche]

Since the newly added test also tests everything the original test file tests, I think the original became redundant.

[ndossche]

Thanks.
Please add an entry to the NEWS file and an entry to UPGRADING. The entry in UPGRADING should contain a short description of the feature and a line that links to your RFC.

[ndossche]

Thanks.
LGTM, I'll wait a bit to see if more feedback comes in but I don't expect that.
I'll merge in a few days if no one else replies.

[Girgias]

Minor nits, but implementation looks good otherwise

[TimWolla]

LGTM except that.