Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:127764
Feedback-ID: id5114917:Fastmail
Message-ID: <efe58859-aa50-4cff-ad80-93712e1cc88f@rwec.co.uk>
Date: Thu, 26 Jun 2025 22:04:32 +0100
Precedence: bulk
MIME-Version: 1.0
User-Agent: Mozilla Thunderbird
Subject: Re: [PHP-DEV] [RFC][DISCUSSION] Object-oriented curl API v2
Content-Language: en-GB
To: internals@lists.php.net
References: <CA+NMNO0K85acCismdBL=8vr5=nKg1_-i0BjXyiqnjoqGAnH3Xw@mail.gmail.com>
 <22a4327d-b27d-4e24-b07a-ae380fe8a0c4@app.fastmail.com>
In-Reply-To: <22a4327d-b27d-4e24-b07a-ae380fe8a0c4@app.fastmail.com>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 8bit
From: imsop.php@rwec.co.uk ("Rowan Tommins [IMSoP]")

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]