Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:127765
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable
Precedence: bulk
Mime-Version: 1.0 (1.0)
Subject: Re: [PHP-DEV] [RFC][DISCUSSION] Object-oriented curl API v2
Date: Thu, 26 Jun 2025 20:20:35 -0300
Message-ID: <08947F7B-7EC5-4349-9FEA-D0768695ACFB@gmail.com>
References: <efe58859-aa50-4cff-ad80-93712e1cc88f@rwec.co.uk>
Cc: internals@lists.php.net
In-Reply-To: <efe58859-aa50-4cff-ad80-93712e1cc88f@rwec.co.uk>
To: Rowan Tommins <imsop.php@rwec.co.uk>
From: deleugyn@gmail.com (=?utf-8?Q?Marco_Aur=C3=A9lio_Deleu?=)


>=20
> On 26 Jun 2025, at 18:07, Rowan Tommins [IMSoP] <imsop.php@rwec.co.uk> wro=
te:
>=20
> =EF=BB=BFOn 26/06/2025 17:53, Larry Garfield wrote:
>=20
>> Now here's the big one: Using enums rather than a bunch of constants is a=
 good change.  However, I feel like it doesn't go far enough.
>=20
>=20
> 100% this.
>=20
> Writing "$ch->setOptionInt(Curl\Option\IntOpt::ConnectTimeout, 30);" inste=
ad of "curl_setopt(CURLOPT_CONNECTTIMEOUT, 30);" is mostly rearranging the p=
unctuation deck-chairs on the ugly code Titanic.
>=20
> Particularly when you can *also* write "$ch->setOptionInt(Curl\Option\IntO=
pt::ConnectTimeoutMs, 30_000);" with the same effect.
>=20
>=20
>=20
>> I realize that would be considerably more work to define all those method=
s (I don't even know how many Curl has, as I rarely use it directly).
>=20
>=20
> I believe there are 272 "CURLOPT_" constants currently documented in the P=
HP manual: https://www.php.net/manual/en/curl.constants.php
>=20
> So, I totally agree that we need a "set raw option" method to support some=
 of the more niche features.
>=20
> But that long list is also exactly why we badly need helpers for common us=
e cases - the manual page for curl_setopt has been at the top of the charts f=
or number of user comments for years, because nobody wants to read the descr=
iptions for two hundred options they'll never need.
>=20
>=20
>=20
>> On 26/06/2025 18:21, Eric Norris wrote:
>> I know that in the prior discussion, Rowan Tommins had a vision for a
>> high-level API (https://externals.io/message/122371#122424)
>=20
>=20
> I think calling it a "vision for a high-level API" is making it sound far m=
ore grandiose than what I suggested. What I suggested, and would still like t=
o see, is a small number of additional methods, for setting really common op=
tions in a more user-friendly way.
>=20
> Looking at my earlier message, my finger-in-the-air number was even smalle=
r than Larry's - a set of 10 methods, each covering a handful of overlapping=
 or closely related options.
>=20
> A single "setHttpMethod" method would bring immediate value, instead of ch=
oosing between CURLOPT_HTTPGET, CURLOPT_POST, CURLOPT_PUT, CURLOPT_NOBODY (f=
or HEAD) and CURLOPT_CUSTOMREQUEST.
>=20
> Adding more helpers in later versions is entirely trivial, but we could se=
t the precedent with a first batch on day one.
>=20
>=20
> The only other "high-level" API I see discussed in the previous thread is s=
plitting the execute() method, for exactly the same reason as splitting setO=
pt(): type safety.
>=20
> public function executeAndReturn(): string
> public function executeAndOutput(): void
> public function executeToFile(Stream $fileHandle): void
> public function executeWithCallback(callable $wrIteFunction): void
>=20
> The CURLOPT_RETURNTRANSFER, CURLOPT_FILE, and CURLOPT_WRITEFUNCTION would t=
hen not exist in the option enum(s), because there would be no way to make u=
se of them.
>=20
> Unlike the helper methods, that's one we have to decide in advance - it wo=
uld be a mess to have those *as well as* a universal "execute(): ?string".
>=20
>=20
> --
> Rowan Tommins
> [IMSoP]


I=E2=80=99m excited at just the discussion of a possibility for PHP to be ab=
le to perform basic HTTP requests in a friendly way. Last month I worked on a=
 solution that involved an SQS Worker that do some work and then sends the o=
utput back to the origin via a HTTP request that is passed as part of the me=
ssage; basically a callback over the wire. However, running it on Serverless=
 as a plugin that makes no assumption about the project state, I couldn=E2=80=
=99t use Guzzle or any composer library for that matter. I had to stick with=
 what=E2=80=99s available on Amazon Linux and Bref, which cURL is, but it=E2=
=80=99s such an unpleasant experience to have to write HTTP requests like it=
=E2=80=99s 2003.=20

I really hope some minor helpers can be added to this OOP version of cURL an=
d I agree that it doesn=E2=80=99t need to be hashed out, perfect or even cov=
er 270 cases. Just a simple GET/POST/PUT/PATCH/DELETE with a string body and=
 some headers manipulation would go 99% of the way already.=