Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:127770
Precedence: bulk
MIME-Version: 1.0
References: <CA+NMNO0K85acCismdBL=8vr5=nKg1_-i0BjXyiqnjoqGAnH3Xw@mail.gmail.com>
 <e52fa8b0-31c7-4280-9d6f-8cb5578a4dce@seld.be>
In-Reply-To: <e52fa8b0-31c7-4280-9d6f-8cb5578a4dce@seld.be>
Date: Fri, 27 Jun 2025 10:01:42 -0300
Message-ID: <CADK1yXK=pV3D5Upe0Nnt_aYTwGe4iB4QdF56Vx5TDQLc97fD=A@mail.gmail.com>
Subject: Re: [PHP-DEV] [RFC][DISCUSSION] Object-oriented curl API v2
To: Jordi Boggiano <j.boggiano@seld.be>
Cc: erictnorris@gmail.com, PHP internals <internals@lists.php.net>
Content-Type: multipart/alternative; boundary="000000000000c46e7806388d4980"
From: deleugyn@gmail.com (Deleu)

--000000000000c46e7806388d4980
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

On Fri, Jun 27, 2025 at 9:24=E2=80=AFAM Jordi Boggiano <j.boggiano@seld.be>=
 wrote:

> On 26.06.2025 18:25, Eric Norris wrote:
> > - uses enumerations for curl options and other curl constants
>
> Overall I think the RFC is a good opportunity to clean up a few legacy
> oddities in the curl API, but I need to throw in my 2c about enum usage
> here, as someone that has actually implemented some complexish
> curl-based client [1].
>
> Currently the API is:
>
>      curl_setopt($h, CURLOPT_SMTH, 3);
>
> Now moving this into multiple enums to me brings one major issue, that I
> first have to think about which type the option has to then know on
> which enum I find it.
>
> I understand this brings type safety on the value side if you have
> multiple setOptionInt etc, but that does not seem worth the trade-off to
> me. Type safety can already be done in static analyzers as they can see
> which option you pass in, they know which value should be allowed.
>
> Then on top of that, assuming we'd put all options in one enum.. I am
> still wondering what the added value is compared to simply having the
> global constants (they could be namespaced if anything...). It's longer
> to type, and does not provide any better autocompletion.
> \Curl\Option::ConnectTimeout vs CURLOPT_CONNECT_TIMEOUT sounds ok to me
> if people feel strongly pro-enum, but I do really hope it is then a
> single enum + setOption() call.
>
> Best,
> Jordi
>
> [1]
>
> https://github.com/composer/composer/blob/main/src/Composer/Util/Http/Cur=
lDownloader.php
>
> Jordi Boggiano
> @seldaek - https://seld.be
>

Reading this I can't help but feel like there's some cognitive bias
*because* you have written a Curl class yourself. The author of a PHP Class
that wraps Curl needs to know about every option and how to translate them
back-and-forth, which is really the insight I take from your message. As a
PHP developer making HTTP requests, I would never have guessed 270 options
for Curl configurations and having them split into multiple Enums gives me
smaller "boxes" that are easier to mentally parse individually. With that
said, splitting enumerations by type rather than context does weaken the
argument of split enums. I wouldn't be instinctively looking for "what enum
do I need that is an int?" or "what enum do I need that is a string?"
unless I already know the implementation details by heart. The Info and
Pause enumerations seem more useful in that regard as they reduce the scope
in which I need to understand, process and decide.

With that said, for me this also threads into the bikeshedding area that
could spiral into a failed RFC. Be it a single Enum for everything,
constants, context-based enums or type-based enums, I would much rather
have this RFC than not have it. PHP is one of the most important Web
applications in the world and it severely lacks the ability to simplify
Http. We could take inspiration from Python Requests [1] or Node Fetch [2]
as a really simple and straightforward API that covers the vast majority of
cases. I take the point that we don't need to go all the way and invent a
RequestClient library in PHP and this RFC is threading on the small step of
converting Curl procedural API into OOP, which is where Larry and Rowans
recommendations about some minor helper methods go a really really long way
compared to where we are today.

[1] https://www.w3schools.com/PYTHON/ref_requests_post.asp
[2] https://nodejs.org/en/learn/getting-started/fetch#basic-post-usage

--=20
Marco Deleu

--000000000000c46e7806388d4980
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

<div dir=3D"ltr"><div dir=3D"ltr"><div dir=3D"ltr"><br></div><br><div class=
=3D"gmail_quote"><div dir=3D"ltr" class=3D"gmail_attr">On Fri, Jun 27, 2025=
 at 9:24=E2=80=AFAM Jordi Boggiano &lt;<a href=3D"mailto:j.boggiano@seld.be=
" target=3D"_blank">j.boggiano@seld.be</a>&gt; wrote:<br></div><blockquote =
class=3D"gmail_quote" style=3D"margin:0px 0px 0px 0.8ex;border-left:1px sol=
id rgb(204,204,204);padding-left:1ex">On 26.06.2025 18:25, Eric Norris wrot=
e:<br>
&gt; - uses enumerations for curl options and other curl constants<br>
<br>
Overall I think the RFC is a good opportunity to clean up a few legacy <br>
oddities in the curl API, but I need to throw in my 2c about enum usage <br=
>
here, as someone that has actually implemented some complexish <br>
curl-based client [1].<br>
<br>
Currently the API is:<br>
<br>
=C2=A0=C2=A0=C2=A0=C2=A0 curl_setopt($h, CURLOPT_SMTH, 3);<br>
<br>
Now moving this into multiple enums to me brings one major issue, that I <b=
r>
first have to think about which type the option has to then know on <br>
which enum I find it.<br>
<br>
I understand this brings type safety on the value side if you have <br>
multiple setOptionInt etc, but that does not seem worth the trade-off to <b=
r>
me. Type safety can already be done in static analyzers as they can see <br=
>
which option you pass in, they know which value should be allowed.<br>
<br>
Then on top of that, assuming we&#39;d put all options in one enum.. I am <=
br>
still wondering what the added value is compared to simply having the <br>
global constants (they could be namespaced if anything...). It&#39;s longer=
 <br>
to type, and does not provide any better autocompletion. <br>
\Curl\Option::ConnectTimeout vs CURLOPT_CONNECT_TIMEOUT sounds ok to me <br=
>
if people feel strongly pro-enum, but I do really hope it is then a <br>
single enum + setOption() call.<br>
<br>
Best,<br>
Jordi<br>
<br>
[1] <br>
<a href=3D"https://github.com/composer/composer/blob/main/src/Composer/Util=
/Http/CurlDownloader.php" rel=3D"noreferrer" target=3D"_blank">https://gith=
ub.com/composer/composer/blob/main/src/Composer/Util/Http/CurlDownloader.ph=
p</a><br>
<br>
Jordi Boggiano<br>
@seldaek - <a href=3D"https://seld.be" rel=3D"noreferrer" target=3D"_blank"=
>https://seld.be</a><br>
</blockquote></div><div><br clear=3D"all"></div><div>Reading this I can&#39=
;t help but feel like there&#39;s some cognitive bias *because* you have wr=
itten a Curl class yourself. The author of a PHP Class that wraps Curl need=
s to know about every option and how to translate them back-and-forth, whic=
h is really the insight I take from your message. As a PHP developer making=
 HTTP requests, I would never have guessed 270 options for Curl configurati=
ons and having them split into multiple Enums gives me smaller &quot;boxes&=
quot; that are easier to mentally parse individually. With that said, split=
ting enumerations by type rather than context does weaken the argument of s=
plit enums. I wouldn&#39;t be instinctively looking for &quot;what enum do =
I need that is an int?&quot; or &quot;what enum do I need that is a string?=
&quot; unless I already know the implementation details by heart. The Info =
and Pause enumerations seem more useful in that regard as they reduce the s=
cope in which I need to understand, process and decide.=C2=A0</div><div><br=
></div><div>With that said, for me this also threads into the bikeshedding =
area that could spiral into a failed RFC. Be it a single Enum for everythin=
g, constants, context-based enums or type-based enums, I would much rather =
have this RFC than not have it. PHP is one of the most important Web applic=
ations in the world and it severely lacks the ability to simplify Http. We =
could take inspiration from Python Requests [1] or Node Fetch [2] as a real=
ly simple and straightforward API that covers the vast majority of cases. I=
 take the point that we don&#39;t need to go all the way and invent a Reque=
stClient library in PHP and this RFC is threading on the small step of conv=
erting Curl procedural API into OOP, which is where Larry and Rowans recomm=
endations about some minor helper methods go a really really long way compa=
red to where we are today.</div><div><br></div><div>[1]=C2=A0<a href=3D"htt=
ps://www.w3schools.com/PYTHON/ref_requests_post.asp" target=3D"_blank">http=
s://www.w3schools.com/PYTHON/ref_requests_post.asp</a></div><div>[2]=C2=A0<=
a href=3D"https://nodejs.org/en/learn/getting-started/fetch#basic-post-usag=
e" target=3D"_blank">https://nodejs.org/en/learn/getting-started/fetch#basi=
c-post-usage</a></div><div><br></div><span class=3D"gmail_signature_prefix"=
>-- </span><br><div dir=3D"ltr" class=3D"gmail_signature"><div dir=3D"ltr">=
<div dir=3D"ltr"><div dir=3D"ltr"><div dir=3D"ltr"><div dir=3D"ltr"><div di=
r=3D"ltr"><div dir=3D"ltr">Marco Deleu</div></div></div></div></div></div><=
/div></div></div>
</div>

--000000000000c46e7806388d4980--