Document clamp function by kylekatarnls · Pull Request #4814 · php/doc-en

kylekatarnls · 2025-08-10T16:33:07Z

See php/php-src#19434

lacatoire · 2026-01-29T09:28:25Z

LGTM, clear, consistent with the RFC, the implementation, and the tests.

Thanks for adding this @kylekatarnls

This PR was merged into the 1.x branch. Discussion ---------- [8.6] Add `clamp` function RFC: https://wiki.php.net/rfc/clamp_v2 Original implementation: php/php-src#19434 Documentation: php/doc-en#4814 Commits ------- 2b4c47d [8.6] Add `clamp` function

jordikroon

We cannot merge this yet as 8.6 isn't released yet.
Mostly doc style comments.

Since date comparison is a big part of this RFC. We should document this explicitly here as well. Not only within the examples section.

jordikroon · 2026-05-10T20:24:49Z

@@ -0,0 +1,34 @@
+<?xml version="1.0" encoding="utf-8"?>


Please don't add file this (yet). While I appreciate your thought, we will have to create migration guides anyway. This would ultimately create a merge conflict when the time is there. And then it would be more easy to merge this.

jordikroon · 2026-05-10T20:28:22Z

+  <para>
+   Return the given value if in range of <parameter>min</parameter> and <parameter>max</parameter>.
+   Else if it's lower than <parameter>min</parameter>, return <parameter>min</parameter>.
+   Else return <parameter>max</parameter>.
+  </para>


Suggested change

<para>

Return the given value if in range of <parameter>min</parameter> and <parameter>max</parameter>.

Else if it's lower than <parameter>min</parameter>, return <parameter>min</parameter>.

Else return <parameter>max</parameter>.

</para>

<simpara>

Return the given value if in range of <parameter>min</parameter> and <parameter>max</parameter>.

Else if it's lower than <parameter>min</parameter>, return <parameter>min</parameter>.

Else return <parameter>max</parameter>.

</simpara>

jordikroon · 2026-05-10T20:28:40Z

+   <para>
+    Values of different types will be compared using the <link linkend="language.operators.comparison">
+    standard comparison rules</link>. For instance, a non-numeric <type>string</type> will be
+    compared to an <type>int</type> as though it were <literal>0</literal>, but multiple non-numeric
+    <type>string</type> values will be compared alphanumerically. The actual value returned will be of the
+    original type with no conversion applied.
+   </para>


Suggested change

<para>

Values of different types will be compared using the <link linkend="language.operators.comparison">

standard comparison rules</link>. For instance, a non-numeric <type>string</type> will be

compared to an <type>int</type> as though it were <literal>0</literal>, but multiple non-numeric

<type>string</type> values will be compared alphanumerically. The actual value returned will be of the

original type with no conversion applied.

</para>

<simpara>

Values of different types will be compared using the <link linkend="language.operators.comparison">

standard comparison rules</link>. For instance, a non-numeric <type>string</type> will be

compared to an <type>int</type> as though it were <literal>0</literal>, but multiple non-numeric

<type>string</type> values will be compared alphanumerically. The actual value returned will be of the

original type with no conversion applied.

</simpara>

jordikroon · 2026-05-10T20:30:15Z

+ </refsect1>
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>


<variablelist> doesn't need to be wrapped in <para>. Could you remove this container?

jordikroon · 2026-05-10T20:30:26Z

+      <para>
+       Any <link linkend="language.operators.comparison">comparable</link>
+       value to be clamped between <parameter>min</parameter> and <parameter>max</parameter>.
+      </para>


Suggested change

<para>

Any <link linkend="language.operators.comparison">comparable</link>

value to be clamped between <parameter>min</parameter> and <parameter>max</parameter>.

</para>

<simpara>

Any <link linkend="language.operators.comparison">comparable</link>

value to be clamped between <parameter>min</parameter> and <parameter>max</parameter>.

</simpara>

jordikroon · 2026-05-10T20:31:34Z

+  <para>
+   If <parameter>value</parameter> is <constant>NAN</constant>, then the returned value will also be
+   <constant>NAN</constant>.
+  </para>


Suggested change

<para>

If <parameter>value</parameter> is <constant>NAN</constant>, then the returned value will also be

<constant>NAN</constant>.

</para>

<simpara>

If <parameter>value</parameter> is <constant>NAN</constant>, then the returned value will also be

<constant>NAN</constant>.

</simpara>

jordikroon · 2026-05-10T20:32:21Z

+  <para>
+   If <parameter>min</parameter> is greater than <parameter>max</parameter>,
+   <function>clamp</function> throws a <classname>ValueError</classname>.
+  </para>


Suggested change

<para>

If <parameter>min</parameter> is greater than <parameter>max</parameter>,

<function>clamp</function> throws a <classname>ValueError</classname>.

</para>

<simpara>

If <parameter>min</parameter> is greater than <parameter>max</parameter>,

<function>clamp</function> throws a <exceptionname>ValueError</exceptionname>.

</simpara>

jordikroon · 2026-05-10T20:32:39Z

+  <para>
+   If <parameter>min</parameter> or <parameter>max</parameter> is <constant>NAN</constant>,
+   <function>clamp</function> throws a <classname>ValueError</classname>.
+  </para>


Suggested change

<para>

If <parameter>min</parameter> or <parameter>max</parameter> is <constant>NAN</constant>,

<function>clamp</function> throws a <classname>ValueError</classname>.

</para>

<simpara>

If <parameter>min</parameter> or <parameter>max</parameter> is <constant>NAN</constant>,

<function>clamp</function> throws a <exceptionname>ValueError</exceptionname>.

</simpara>

jordikroon · 2026-05-10T20:33:46Z

+  <para>
+   <example>
+    <title>Example uses of <function>clamp</function></title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+echo clamp(-5, min: 0, max: 100), PHP_EOL;  // 0
+echo clamp(55, min: 0, max: 100), PHP_EOL;  // 55
+echo clamp(103, min: 0, max: 100), PHP_EOL;  // 100
+
+echo clamp("J", min: "A", max: "F"), PHP_EOL;  // "F"
+
+clamp(
+    new \DateTimeImmutable('2025-08-01'),
+    min: new \DateTimeImmutable('2025-08-15'),
+    max: new \DateTimeImmutable('2025-09-15'),
+)->format('Y-m-d'), PHP_EOL; // 2025-08-15
+?>
+]]>
+    </programlisting>
+   </example>
+  </para>


Suggested change

<para>

<example>

<title>Example uses of <function>clamp</function></title>

<programlisting role="php">

<![CDATA[

<?php

echo clamp(-5, min: 0, max: 100), PHP_EOL; // 0

echo clamp(55, min: 0, max: 100), PHP_EOL; // 55

echo clamp(103, min: 0, max: 100), PHP_EOL; // 100

echo clamp("J", min: "A", max: "F"), PHP_EOL; // "F"

clamp(

new \DateTimeImmutable('2025-08-01'),

min: new \DateTimeImmutable('2025-08-15'),

max: new \DateTimeImmutable('2025-09-15'),

)->format('Y-m-d'), PHP_EOL; // 2025-08-15

?>

]]>

</programlisting>

</example>

</para>

<informalexample>

<programlisting role="php">

<![CDATA[

<?php

echo clamp(-5, min: 0, max: 100), PHP_EOL; // 0

echo clamp(55, min: 0, max: 100), PHP_EOL; // 55

echo clamp(103, min: 0, max: 100), PHP_EOL; // 100

echo clamp("J", min: "A", max: "F"), PHP_EOL; // "F"

clamp(

new \DateTimeImmutable('2025-08-01'),

min: new \DateTimeImmutable('2025-08-15'),

max: new \DateTimeImmutable('2025-09-15'),

)->format('Y-m-d'), PHP_EOL; // 2025-08-15

?>

]]>

</programlisting>

</informalexample>

jordikroon · 2026-05-10T20:34:18Z

+ </refsect1>
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>


Could you remove this outer <para>?

This was referenced Aug 10, 2025

Document clamp function php/doc-fr#2237

Open

[RFC] Add clamp function php/php-src#19434

Merged

kylekatarnls force-pushed the clamp-function branch from b4c8f1f to ddab889 Compare August 10, 2025 17:26

kylekatarnls mentioned this pull request Nov 19, 2025

[8.6] Add clamp function symfony/polyfill#554

Merged

kylekatarnls force-pushed the clamp-function branch from ddab889 to 19f924c Compare November 19, 2025 09:39

Document clamp function

1b1ac7b

kylekatarnls force-pushed the clamp-function branch from 19f924c to 1b1ac7b Compare November 19, 2025 09:41

kylekatarnls marked this pull request as ready for review December 7, 2025 15:23

lacatoire approved these changes Jan 29, 2026

View reviewed changes

jordikroon requested changes May 10, 2026

View reviewed changes

jordikroon added this to the PHP 8.6 milestone May 18, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Document clamp function#4814

Document clamp function#4814
kylekatarnls wants to merge 1 commit into
php:masterfrom
kylekatarnls:clamp-function

kylekatarnls commented Aug 10, 2025

Uh oh!

lacatoire commented Jan 29, 2026

Uh oh!

jordikroon left a comment

Uh oh!

jordikroon May 10, 2026

Uh oh!

jordikroon May 10, 2026

Uh oh!

jordikroon May 10, 2026

Uh oh!

jordikroon May 10, 2026

Uh oh!

jordikroon May 10, 2026

Uh oh!

jordikroon May 10, 2026

Uh oh!

jordikroon May 10, 2026

Uh oh!

jordikroon May 10, 2026

Uh oh!

jordikroon May 10, 2026

Uh oh!

jordikroon May 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

kylekatarnls commented Aug 10, 2025

Uh oh!

lacatoire commented Jan 29, 2026

Uh oh!

jordikroon left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants