Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:127759
Feedback-ID: i8414410d:Fastmail
Precedence: bulk
MIME-Version: 1.0
Date: Thu, 26 Jun 2025 11:53:46 -0500
To: "php internals" <internals@lists.php.net>
Message-ID: <22a4327d-b27d-4e24-b07a-ae380fe8a0c4@app.fastmail.com>
In-Reply-To: 
 <CA+NMNO0K85acCismdBL=8vr5=nKg1_-i0BjXyiqnjoqGAnH3Xw@mail.gmail.com>
References: 
 <CA+NMNO0K85acCismdBL=8vr5=nKg1_-i0BjXyiqnjoqGAnH3Xw@mail.gmail.com>
Subject: Re: [PHP-DEV] [RFC][DISCUSSION] Object-oriented curl API v2
Content-Type: text/plain
Content-Transfer-Encoding: 7bit
From: larry@garfieldtech.com ("Larry Garfield")

On Thu, Jun 26, 2025, at 11:25 AM, Eric Norris wrote:
> Hello Internals,
>
> I'd like to formally propose a restart of the original object-oriented
> curl API RFC (https://wiki.php.net/rfc/curl-oop):
>
> https://wiki.php.net/rfc/curl_oop_v2
>
> The prior RFC seemed to get positive feedback, with a small consensus
> around wanting enum(s) for curl options. I've taken that feedback and
> incorporated it into a new RFC, as I am not the original author, but I
> am interested in making another potential improvement to the curl
> extension.
>
> In a nutshell, this version of the RFC:
>
> - uses enumerations for curl options and other curl constants
> - introduces a new Curl namespace
>
> I have not yet created an implementation PR. I realize that is
> somewhat discouraged, but I believe that this should be relatively
> straightforward to implement (there's also the previous RFC's PR to
> build on top of). The implementation of this RFC as it is now will
> likely be tedious, however, so I'd like to get feedback on the
> enumeration idea before committing to the work.
>
> I've outlined one open question in the RFC, which relates to the above:
>
> - Should we organize the curl option enumerations by value type? Or
> have a single enumeration for all curl_setopt options and another for
> all curl_multi_setopt options?
>
> If others (including the original RFC author) are interested in
> working with me on this, I'm more than open to that, so please let me
> know.
>
> Thanks,
> Eric

I still support this effort.

1. I don't think the Curl\Option namespace is necessary.  They can just be in the main Curl namespace.

2. Please don't name the exception "Exception".  It needs some slightly more useful name, to avoid confusion in a file that also uses \Exception.

3. I realize `Handle` is the name from the procedural API, but it's not very self-descriptive.  Without knowing Curl, it's non-obvious that it's a self-executing request object.  Is there a better name we could find while we're at it?

4. Love the use of aviz. :-)

5. 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.  

For instance, 

$ch = new Curl\Handle("https://example.com")
    ->setOptionInt(Curl\Option\IntOpt::ConnectTimeout, 30)
    ->setOptionBool(Curl\Option\BoolOpt::FollowLocation, true);

Would be 10x easier to use were it:

$ch = new Curl\Handle("https://example.com")
    ->setConnectionTimeout(30)
    ->setFollowLocation((true);

Or for that matter, properties would now allow for those to even just be set directly on typed properties.  (Though it wouldn't be chainable.)

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).  But it would result in a vastly easier to use API than "set some random integer-based field(EnumName, 30)".  The latter is highly non-obvious.  Especially when getting into POST requests with different body formats (something the RFC should include examples of), IMO, good ergonomics is more important than looking like the old, horribly obtuse API.

As a worst case, perhaps the top-20 options or so could be converted to methods/properties, and the rest left to be ugly flags?

--Larry Garfield