Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:127767
Precedence: bulk
MIME-Version: 1.0
References: <CA+NMNO0K85acCismdBL=8vr5=nKg1_-i0BjXyiqnjoqGAnH3Xw@mail.gmail.com>
 <22a4327d-b27d-4e24-b07a-ae380fe8a0c4@app.fastmail.com> <efe58859-aa50-4cff-ad80-93712e1cc88f@rwec.co.uk>
In-Reply-To: <efe58859-aa50-4cff-ad80-93712e1cc88f@rwec.co.uk>
Reply-To: erictnorris@gmail.com
Date: Thu, 26 Jun 2025 23:51:11 -0400
Message-ID: <CA+NMNO3DyYQSi6M4BwhbBhocu=2ToA5=6ZLYiQ5oXr1sUj7E5w@mail.gmail.com>
Subject: Re: [PHP-DEV] [RFC][DISCUSSION] Object-oriented curl API v2
To: "Rowan Tommins [IMSoP]" <imsop.php@rwec.co.uk>
Cc: internals@lists.php.net
Content-Type: text/plain; charset="UTF-8"
From: eric.t.norris@gmail.com (Eric Norris)

Thanks Rowan!

> I think calling it a "vision for a high-level API" is making it sound
> far more grandiose than what I suggested. What I suggested, and would
> still like to see, is a small number of additional methods, for setting
> really common options in a more user-friendly way.

I apologize for misrepresenting your suggestion. I was mainly
responding to your "the eventual aim should be that users don't need a
userland wrapper" comment, which I worry sounds closer to what Ben was
(I believe) objecting to - a higher-level wrapper. Upon re-reading
though, I think that's potentially an unfair take - you did go on to
say "...just to make a simple request in a readable way".

> Looking at my earlier message, my finger-in-the-air number was even
> smaller than Larry's - a set of 10 methods, each covering a handful of
> overlapping or closely related options.
>
> A single "setHttpMethod" method would bring immediate value, instead of
> choosing between CURLOPT_HTTPGET, CURLOPT_POST, CURLOPT_PUT,
> CURLOPT_NOBODY (for HEAD) and CURLOPT_CUSTOMREQUEST.
>
> Adding more helpers in later versions is entirely trivial, but we could
> set the precedent with a first batch on day one.

I'm not opposed to this, but I am - as previously stated - nervous
about how and where we draw this line, since I expect there may be a
lot of opinions here. That said, if the general consensus is that we
want direct methods or properties for the N most common use-cases, I'm
happy to make that change to the RFC.

I can try to take a look at the curl options and do some github
searches to see if I can identify common patterns. I agree that
setting the HTTP method and timeout are good contenders. If someone
else wants to propose a list as well, feel free!

> The only other "high-level" API I see discussed in the previous thread
> is splitting the execute() method, for exactly the same reason as
> splitting setOpt(): type safety.
>
> public function executeAndReturn(): string
> public function executeAndOutput(): void
> public function executeToFile(Stream $fileHandle): void
> public function executeWithCallback(callable $wrIteFunction): void
>
> The CURLOPT_RETURNTRANSFER, CURLOPT_FILE, and CURLOPT_WRITEFUNCTION
> would then not exist in the option enum(s), because there would be no
> way to make use of them.
>
> Unlike the helper methods, that's one we have to decide in advance - it
> would be a mess to have those *as well as* a universal "execute(): ?string".

If we were to go this route, I would suggest:

public function fetch(): string
public function execute(resource|callable $out): void

that is, one method to just return the contents of the URL, and
another to either write output to a file (including STDOUT, if the
user desires), or to send output to a write callback.