> > On 26 Jun 2025, at 18:07, Rowan Tommins [IMSoP] <imsop....@rwec.co.uk> wrote: > > On 26/06/2025 17:53, Larry Garfield wrote: > >> 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. > > > 100% this. > > Writing "$ch->setOptionInt(Curl\Option\IntOpt::ConnectTimeout, 30);" instead > of "curl_setopt(CURLOPT_CONNECTTIMEOUT, 30);" is mostly rearranging the > punctuation deck-chairs on the ugly code Titanic. > > Particularly when you can *also* write > "$ch->setOptionInt(Curl\Option\IntOpt::ConnectTimeoutMs, 30_000);" with the > same effect. > > > >> I realize that would be considerably more work to define all those methods >> (I don't even know how many Curl has, as I rarely use it directly). > > > I believe there are 272 "CURLOPT_" constants currently documented in the PHP > manual: https://www.php.net/manual/en/curl.constants.php > > So, I totally agree that we need a "set raw option" method to support some of > the more niche features. > > But that long list is also exactly why we badly need helpers for common use > cases - the manual page for curl_setopt has been at the top of the charts for > number of user comments for years, because nobody wants to read the > descriptions for two hundred options they'll never need. > > > >> 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) > > > 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. > > 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. > > > 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". > > > -- > Rowan Tommins > [IMSoP]
I’m excited at just the discussion of a possibility for PHP to be able 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 output back to the origin via a HTTP request that is passed as part of the message; basically a callback over the wire. However, running it on Serverless as a plugin that makes no assumption about the project state, I couldn’t use Guzzle or any composer library for that matter. I had to stick with what’s available on Amazon Linux and Bref, which cURL is, but it’s such an unpleasant experience to have to write HTTP requests like it’s 2003. I really hope some minor helpers can be added to this OOP version of cURL and I agree that it doesn’t need to be hashed out, perfect or even cover 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.
