Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:128540
Feedback-ID: ifab94697:Fastmail
Precedence: list
MIME-Version: 1.0
Date: Sat, 23 Aug 2025 12:02:48 +0200
To: internals@lists.php.net
Message-ID: <bae5adb0-7b81-4178-915c-5d7c2633f1c0@app.fastmail.com>
In-Reply-To: <cbd359d2-c80a-4ae1-b9c3-16e2cbfc617a@app.fastmail.com>
References: 
 <CANBC5np5gFoG2vy572K_rV5df58qBJdQuKsmYdHiprA2mLPWUg@mail.gmail.com>
 <c9acda400885e3c78775e400cb492538@bastelstu.be>
 <CANBC5noypta7=YvVaAB6sPFhQKQCxJTFMQZ7fEShii2isya49A@mail.gmail.com>
 <0027ab13-89fb-40b4-991b-2f88a35c2f31@gmx.de>
 <CANBC5npgKA2T51t9=CD8LcqZsbLY-mW1GUepyGkZLPEGtVxoPA@mail.gmail.com>
 <272c241b-3145-4069-8a6a-9ea877f936c0@app.fastmail.com>
 <CANBC5npestDfHkGVd8LPZyz8Wxx4zuQApj5C-d=qp0Q=tvCVTQ@mail.gmail.com>
 <cbd359d2-c80a-4ae1-b9c3-16e2cbfc617a@app.fastmail.com>
Subject: Re: [PHP-DEV] [RFC] Add clamp function
Content-Type: multipart/alternative;
 boundary=8d6d3b394a384e3e86851de375f96952
From: rob@bottled.codes ("Rob Landers")

--8d6d3b394a384e3e86851de375f96952
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable



On Fri, Aug 22, 2025, at 22:09, Larry Garfield wrote:
> On Fri, Aug 22, 2025, at 12:45 PM, Kyle Katarn wrote:
>=20
> > About "What determines comparability", it follows the usual rules of=20
> > PHP: https://www.php.net/manual/en/language.operators.comparison.php
> >
> > So it's equivalent to ($value < $min) ? $min : (($value > $max) ? $m=
ax=20
> > : $value) and also equivalent to min($max, max($min, $value))
> >
> > About clamp(new Point(1, 2), new Point(0, 0), new Point(5, 5));
> >
> > If Point is a comparable value (simple DTO for example), it should=20
> > return $value, like when doing ($value < $min) ? $min : (($value >=20
> > $max) ? $max : $value) we could add a test for such case, but I thin=
k=20
> > that for consistency, whatever currently works in min() should work =
in=20
> > clamp()
> >
> > Following the link of the implementation, there is also a link to th=
e=20
> > documentation where I already explained the comparison rules followi=
ng=20
> > the example of what was done in the documentation for min() and max(=
):=20
> > https://github.com/php/doc-en/pull/4814
>=20
> Please make sure the above is captured in the RFC.
>=20
> Though apparently what PHP currently does with Point comparisons in mi=
n/max is... weird.  I don't even know what the logic here is. :)
>=20
> https://3v4l.org/pTmiV
>=20
> (No need to change it in this RFC, just note explicitly that the expec=
ted behavior is identical to that min(max()) construct, regardless of ty=
pe.)
>=20
> --Larry Garfield
>=20

It only compares the first property, and if there is a conflict, it move=
s on to the next property. That is why some of us have been advocating f=
or operator overrides: because this default isn=E2=80=99t always appropr=
iate, as your Point example illustrates. In some cases, you would want t=
o compare magnitude or something else entirely, not just the x value.

What is even trickier is that this process completely ignores computed h=
ooks. So, if you add a hook as the first property (for example, returnin=
g the magnitude), it is simply ignored. As a weird side note: if you cas=
t the object to an array, the computed hook disappears, but if you use `=
json_encode()`, the computed value is included.

To complicate things further, the current behaviour for objects is actua=
lly =E2=80=9Cundefined=E2=80=9D and it isn=E2=80=99t documented. There a=
re examples that show how objects are compared, but they don=E2=80=99t e=
xplicitly mention that the object is being cast to an array (see the abo=
ve paragraph on why that matters). Because this relies on implementation=
 details rather than documented behaviour, it could change between PHP v=
ersions without an RFC. That makes relying on it a bit risky.

Adding operator overrides would help by making this behaviour explicit a=
nd consistent across versions, or just defining it in general. But whene=
ver someone tries to define this more clearly (as I started to do with R=
ecords), it tends to run into resistance on this list for reasons I=E2=80=
=99ve never quite understood.

=E2=80=94 Rob
--8d6d3b394a384e3e86851de375f96952
Content-Type: text/html; charset=utf-8
Content-Transfer-Encoding: quoted-printable

<!DOCTYPE html><html><head><title></title></head><body><div><br></div><d=
iv><br></div><div>On Fri, Aug 22, 2025, at 22:09, Larry Garfield wrote:<=
/div><blockquote type=3D"cite" id=3D"qt" style=3D""><div>On Fri, Aug 22,=
 2025, at 12:45 PM, Kyle Katarn wrote:</div><div><br></div><div>&gt; Abo=
ut "What determines comparability", it follows the usual rules of&nbsp;<=
/div><div>&gt; PHP:&nbsp;<a href=3D"https://www.php.net/manual/en/langua=
ge.operators.comparison.php">https://www.php.net/manual/en/language.oper=
ators.comparison.php</a></div><div>&gt;</div><div>&gt; So it's equivalen=
t to ($value &lt; $min) ? $min : (($value &gt; $max) ? $max&nbsp;</div><=
div>&gt; : $value) and also equivalent to min($max, max($min, $value))</=
div><div>&gt;</div><div>&gt; About clamp(new Point(1, 2), new Point(0, 0=
), new Point(5, 5));</div><div>&gt;</div><div>&gt; If Point is a compara=
ble value (simple DTO for example), it should&nbsp;</div><div>&gt; retur=
n $value, like when doing ($value &lt; $min) ? $min : (($value &gt;&nbsp=
;</div><div>&gt; $max) ? $max : $value) we could add a test for such cas=
e, but I think&nbsp;</div><div>&gt; that for consistency, whatever curre=
ntly works in min() should work in&nbsp;</div><div>&gt; clamp()</div><di=
v>&gt;</div><div>&gt; Following the link of the implementation, there is=
 also a link to the&nbsp;</div><div>&gt; documentation where I already e=
xplained the comparison rules following&nbsp;</div><div>&gt; the example=
 of what was done in the documentation for min() and max():&nbsp;</div><=
div>&gt;&nbsp;<a href=3D"https://github.com/php/doc-en/pull/4814">https:=
//github.com/php/doc-en/pull/4814</a></div><div><br></div><div>Please ma=
ke sure the above is captured in the RFC.</div><div><br></div><div>Thoug=
h apparently what PHP currently does with Point comparisons in min/max i=
s... weird.&nbsp; I don't even know what the logic here is. :)</div><div=
><br></div><div><a href=3D"https://3v4l.org/pTmiV">https://3v4l.org/pTmi=
V</a></div><div><br></div><div>(No need to change it in this RFC, just n=
ote explicitly that the expected behavior is identical to that min(max()=
) construct, regardless of type.)</div><div><br></div><div>--Larry Garfi=
eld</div><div><br></div></blockquote><div><br></div><div>It only compare=
s the first property, and if there is a conflict, it moves on to the nex=
t property. That is why some of us have been advocating for operator ove=
rrides: because this default isn=E2=80=99t always appropriate, as your P=
oint example illustrates. In some cases, you would want to compare magni=
tude or something else entirely, not just the x value.</div><div><br></d=
iv><div>What is even trickier is that this process completely ignores co=
mputed hooks. So, if you add a hook as the first property (for example, =
returning the magnitude), it is simply ignored. As a weird side note: if=
 you cast the object to an array, the computed hook disappears, but if y=
ou use <code style=3D"border-top-width:1px;border-right-width:1px;border=
-bottom-width:1px;border-left-width:1px;border-top-style:solid;border-ri=
ght-style:solid;border-bottom-style:solid;border-left-style:solid;border=
-top-color:rgb(204, 204, 204);border-right-color:rgb(204, 204, 204);bord=
er-bottom-color:rgb(204, 204, 204);border-left-color:rgb(204, 204, 204);=
border-image-source:initial;border-image-slice:initial;border-image-widt=
h:initial;border-image-outset:initial;border-image-repeat:initial;border=
-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-rad=
ius:3px;border-bottom-left-radius:3px;background-image:initial;backgroun=
d-position-x:initial;background-position-y:initial;background-size:initi=
al;background-repeat:initial;background-attachment:initial;background-or=
igin:initial;background-clip:initial;background-color:rgb(246, 246, 246)=
;font-family:menlo, consolas, monospace;font-size:90%;padding-top:1px;pa=
dding-right:3px;padding-bottom:1px;padding-left:3px;">json_encode()</cod=
e>, the computed value is included.</div><div><br></div><div>To complica=
te things further, the current behaviour for objects is actually =E2=80=9C=
undefined=E2=80=9D and it isn=E2=80=99t documented. There are examples t=
hat show how objects are compared, but they don=E2=80=99t explicitly men=
tion that the object is being cast to an array (see the above paragraph =
on why that matters). Because this relies on implementation details rath=
er than documented behaviour, it could change between PHP versions witho=
ut an RFC. That makes relying on it a bit risky.</div><div><br></div><di=
v>Adding operator overrides would help by making this behaviour explicit=
 and consistent across versions, or just defining it in general. But whe=
never someone tries to define this more clearly (as I started to do with=
 Records), it tends to run into resistance on this list for reasons I=E2=
=80=99ve never quite understood.</div><div><br></div><div>=E2=80=94 Rob<=
br></div></body></html>
--8d6d3b394a384e3e86851de375f96952--