Newsgroups: php.internals Path: news.php.net Xref: news.php.net php.internals:127778 X-Original-To: internals@lists.php.net Delivered-To: internals@lists.php.net Received: from php-smtp4.php.net (php-smtp4.php.net [45.112.84.5]) by lists.php.net (Postfix) with ESMTPS id 721CD1A00BC for ; Fri, 27 Jun 2025 22:06:32 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=php.net; s=mail; t=1751061877; bh=LmVnvc9Y0onacbjvsmjHpJ4k9Fs/h9jf5amOq907EnQ=; h=References:In-Reply-To:From:Date:Subject:To:Cc:From; b=JdDRbbAyiV9UOgSlwOLY2oJyMgcEB6/BwWEzAovjI50b1yjIFQ4E2aNYJ49yKgQAI N5XDAYY4mhoxtc7H30SrtiDt9qwr5F455SNQiLBYC8jcggBJZk/iOK/XVSvNyZXBiW 6tFte7hRNAJIywlkrj8oYRZO4Bo1oluKYmBiYJLdR9FPpDvBoMM9YKAmVGYMIKpRx3 lTTyt3eTMiEhZyk3oUfNtd5gj8d/3c2kEicKVBX8JX98q9qzLirVAuB35UwU+rPs2e Y6FUOxrBJIc0NWJx/hZZ/7L/WjFgjNW19/ULmItvrbf1B/UKU8t0s1A2sSgOjyz/dy mTybKbuJheuGA== Received: from php-smtp4.php.net (localhost [127.0.0.1]) by php-smtp4.php.net (Postfix) with ESMTP id BBC7518006C for ; Fri, 27 Jun 2025 22:04:36 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 4.0.1 (2024-03-25) on php-smtp4.php.net X-Spam-Level: X-Spam-Status: No, score=-1.2 required=5.0 tests=BAYES_20,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,DMARC_PASS,FREEMAIL_FROM, HTML_MESSAGE,RCVD_IN_DNSWL_NONE,RCVD_IN_MSPIKE_H2,SPF_HELO_NONE, SPF_PASS autolearn=no autolearn_force=no version=4.0.1 X-Spam-Virus: Error (Cannot connect to unix socket '/var/run/clamav/clamd.ctl': connect: Connection refused) X-Envelope-From: Received: from mail-lj1-f170.google.com (mail-lj1-f170.google.com [209.85.208.170]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by php-smtp4.php.net (Postfix) with ESMTPS for ; Fri, 27 Jun 2025 22:04:36 +0000 (UTC) Received: by mail-lj1-f170.google.com with SMTP id 38308e7fff4ca-32b910593edso21313941fa.1 for ; Fri, 27 Jun 2025 15:06:30 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1751061989; x=1751666789; darn=lists.php.net; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:from:to:cc:subject:date:message-id:reply-to; bh=sZ8UWKZ/CqKTQ8Wn7FSQj0rMLAuiR8H4jvP2+3Z7dmA=; b=Fr+L7qIP5XANUhKl/WBdWL3otpK3h2TWqNR366g0AhnuLFZdFUB2Qg/uOpjh5CWJJ8 2iCiXsZyYr3k8jNq6SB/HwecZLJBKRhtExvmPok1RopIktXDNTNu1ktGg1JjepKKlPPx CPdf8VaaN4TlYh/7Ffrd8Srugj5JwOd3L1GrVhYYiR0rX7JduYuFlycbLVBWUpP6Pzvu sKGRTmYJO2CRVjdjgjb6pApWjhYdowo2k3Yec2okiPBteEhSwvWaHWt9VdcmiUd3XRFV neoZ6vA+aW9wotV+WIA6HPO4dZDWDcBvrwK6EqbDuZu6NbzDtrvBuJ+DafR/SogJNsHJ gb3Q== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1751061989; x=1751666789; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=sZ8UWKZ/CqKTQ8Wn7FSQj0rMLAuiR8H4jvP2+3Z7dmA=; b=On1NNfwebHpMILXIsoiAJveOodSH/0dE8VmXvCMuO9iD41TMKLdCDhAPgrVmkI39M6 ADTRVlx7NMBCiGY+hpZary7jZYAXyxSsuATeaPnn/9dVKkhm1fMTMudOJwqSJRfphRjR +GtTzLDQ6UxCBtvCfNVKuzRGyVfAOTrPjiztlgOZRhzB+OKsH4aXTjj0ZNQ67Gs1MSFv KYEZKkX5JwBHq9tLVJDgtJ7XIDOvX6BnENRKXuJxBaV7qr5C1Qjq5e5J2brDehdeqD/a yHieH3cC/FXfvmj9LU8uJWFNHJWTPYOEX5j0Aoz3YG7/rtWiCsl5f2bH756wRfvfEIBt nEYA== X-Forwarded-Encrypted: i=1; AJvYcCWfGw3xzNdVmhG+XobXbvt0JmAJKoVI4Vc0MqJAArI8ce+D0PNMs1wdv5qsoNK10TDPj+18FoSAa5k=@lists.php.net X-Gm-Message-State: AOJu0YyOsw05qlRbhzHfFnLG0y8tO6SWvzjEnH1EvIQMXjYknM0HJr9r AU1Nq1emRucXy8zc53n3qplNGGmTtZpuVe9jRhCVWAAfQewjsSXe9Qhej8iwm7HZSGq+vMBBKQn 7D5O+bCPb6HBpAiX8i5/Jr0jePoQuxNg= X-Gm-Gg: ASbGnctGGfv0qqK+zkqTklJmbBQy7oTlz2m92BoZaZb+QHgVCNPCcEtmL93TL4sS43Y WoHz/uNVhjJlE3hOaFFj5JAnYg3pOflX+KUe3AkDIRCa20aXStCOnQfe8csIbJrzkJqtlF2UmGk hyBzuLJIMnq9h+Eu+KXiJL8afg8TXVfrvHBLzKkkQsK9o= X-Google-Smtp-Source: AGHT+IFQ7bKgZXlyVq7jGC8AIG5fYd+r70fnpmld807o1BBSr32qlkax6zg5Mt+EB0vNCrVIVyXEHjwiZmAeYA3ariw= X-Received: by 2002:a05:651c:41d0:b0:32b:4c14:ee3 with SMTP id 38308e7fff4ca-32cdc5545cfmr12102051fa.37.1751061988839; Fri, 27 Jun 2025 15:06:28 -0700 (PDT) Precedence: bulk list-help: list-post: List-Id: internals.lists.php.net x-ms-reactions: disallow MIME-Version: 1.0 References: In-Reply-To: Date: Sat, 28 Jun 2025 00:06:16 +0200 X-Gm-Features: Ac12FXzD5LqY3GSsDQBRv0J3s1QaFQsGCM0S9e_Sq5aJbNHA9loTeu8l7TMGPzU Message-ID: Subject: Re: [PHP-DEV] [RFC][DISCUSSION] Object-oriented curl API v2 To: Ayesh Karunaratne Cc: erictnorris@gmail.com, PHP internals Content-Type: multipart/alternative; boundary="000000000000d31457063894e3ed" From: nicolas.grekas+php@gmail.com (Nicolas Grekas) --000000000000d31457063894e3ed Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable Le sam. 28 juin 2025 =C3=A0 00:01, Ayesh Karunaratne a = =C3=A9crit : > > 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 > > Thank you for taking the initiative to work on this. It's long > overdue, and the pattern we have now =E2=80=94 that a `CurlHandle` object= is > passed to functions =E2=80=94 is not as intuitive as calling a method on = that > object. > > However, I softly oppose this RFC in its current state and the way it > seems to be going. > > I have pushed Curl and libcurl to some uncommon cases such as HTTP/3, > DoH, the new debug callback (which I authored the PR for), IMAP, and a > few other obscure tweaks. For all of them, the current `curl_setopt` > worked, and the more I used it, the more I understood that having just > a few Curl functions and a sea of Curl options is the least > "presumptive way", regardless of the protocol and the options Curl > provides. > > The extension is named `Curl`, because it's supposed to provide Curl > functionality into PHP. It provides low-level functionality, but we > should leave it to the PHP users to build the libraries that have > fluent APIs. > > This way, we can have excellent purpose-built HTTP clients, IMAP > clients, Tor proxies, etc, all built using the low-level functionality > the extension offers.The HTTP client authors know the Curl options > really well to build a secure and fast HTTP client, and someone else > building an IMAP client can provide an intuitive API but still use the > same underlying Curl functionality. I understand that your RFC does > not propose a high-level API, and I agree with you that a high-level > API will need a lot of discussion. > > There's a ton of Curl constants, and you are right that it could > really use some organizing. The upstream Curl project has not done it, > most likely because the options behave differently depending on the > protocol, and simply because it's a lot of work and BC trouble to do > so. I don=E2=80=99t think we can realistically have a meaningful discours= e on > how to semantically group the constants into meaningful Enums. I'd > also argue that if libcurl is OK with having a sea of Curl options, we > should not be the one to group them. > > Grouping them by the expected value type is one way to do it, but as > mentioned elsewhere in replies, now, the consumers of the API will > have to figure out whether that one Curl option they always used > belongs to `IntOpt` or a `BoolOpt`. It will help with > `CURLOPT_SSL_VERIFYHOST` (which should be set to `2`, not `true`), but > I don't think this level of type safety is all that useful for the > trouble. > > To bring some numbers, we currently have: > > - 271 CURLOPT_* consts (https://php.watch/codex?search=3DCURLOPT_) > - 78 CURLINFO_* consts (https://php.watch/codex?search=3DCURLINFO_) > - 71 CURLE_* consts (https://php.watch/codex?search=3DCURLE_) + I sent > a PR to add 41 missing consts > (https://github.com/php/php-src/pull/13340/files) > - 150+ constants for options such as protocols, HTTP versions, URL > follow rules, etc. > > I think a more light-weight approach would be to: > > - Move all of them to the `\Curl` namespace. > - Rename Curl options to `\Curl\Option` namespace, and rename them, > so that `CURLOPT_SSL_VERIFYHOST` becomes `Curl\Option\SSL_VERIFYHOST` > - Rename Curl error codes to similar `\Curl\Error` constants. > - Have the `CurlHandle` object accept options, e.g. > `$ch->setOption(Curl\Option\SSL_VERIFYHOST, 2)`. libcurl Easy handlers > do not have a way to retrieve the option once it's set, so there will > be no `getOption` either. > - Make Curl throw exceptions, and never `false` on `\Curl\execute()`, > with the Exception's error code and message mapped to the Curl error > code and message. We will not need to bring over `curl_error` or > `curl_errno` functions. > > Realistically, I don't think we can deprecate and remove the `\curl_*` > functions any time soon, so this will actually add more maintenance > work for php-src at the end too. > > Thank you. > Ayesh. > I'm not even sure it's a good idea to add those namespaced options: using CURLOPT_SSL_VERIFYHOST is perfect to find the corresponding curl documentation with your favorite search engine. php's doc is awesome, but it cannot compete with the details provided by curl's doc on the topic. Nicolas --000000000000d31457063894e3ed Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable


Le=C2=A0sam. 28= juin 2025 =C3=A0=C2=A000:01, Ayesh Karunaratne <ayesh@php.watch> a = =C3=A9crit=C2=A0:
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<= br> > 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 a= bove:
>
> - Should we organize the curl option enumerations by value type? Or > have a single enumeration for all curl_setopt options and another for<= br> > 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

Thank you for taking the initiative to work on this. It's long
overdue, and the pattern we have now =E2=80=94 that a `CurlHandle` object i= s
passed to functions =E2=80=94 is not as intuitive as calling a method on th= at
object.

However, I softly oppose this RFC in its current state and the way it
seems to be going.

I have pushed Curl and libcurl to some uncommon cases such as HTTP/3,
DoH, the new debug callback (which I authored the PR for), IMAP, and a
few other obscure tweaks. For all of them, the current `curl_setopt`
worked, and the more I used it, the more I understood that having just
a few Curl functions and a sea of Curl options is the least
"presumptive way", regardless of the protocol and the options Cur= l
provides.

The extension is named `Curl`, because it's supposed to provide Curl functionality into PHP. It provides low-level functionality, but we
should leave it to the PHP users to build the libraries that have
fluent APIs.

This way, we can have excellent purpose-built HTTP clients, IMAP
clients, Tor proxies, etc, all built using the low-level functionality
the extension offers.The HTTP client authors know the Curl options
really well to build a secure and fast HTTP client, and someone else
building an IMAP client can provide an intuitive API but still use the
same underlying Curl functionality. I understand that your RFC does
not propose a high-level API, and I agree with you that a high-level
API will need a lot of discussion.

There's a ton of Curl constants, and you are right that it could
really use some organizing. The upstream Curl project has not done it,
most likely because the options behave differently depending on the
protocol, and simply because it's a lot of work and BC trouble to do so. I don=E2=80=99t think we can realistically have a meaningful discourse = on
how to semantically group the constants into meaningful Enums. I'd
also argue that if libcurl is OK with having a sea of Curl options, we
should not be the one to group them.

Grouping them by the expected value type is one way to do it, but as
mentioned elsewhere in replies, now, the consumers of the API will
have to figure out whether that one Curl option they always used
belongs to `IntOpt` or a `BoolOpt`. It will help with
`CURLOPT_SSL_VERIFYHOST` (which should be set to `2`, not `true`), but
I don't think this level of type safety is all that useful for the
trouble.

To bring some numbers, we currently have:

=C2=A0- 271 CURLOPT_* consts (https://php.watch/codex?searc= h=3DCURLOPT_)
=C2=A0- 78 CURLINFO_* consts (https://php.watch/codex?sear= ch=3DCURLINFO_)
=C2=A0- 71 CURLE_* consts (https://php.watch/codex?search=3DC= URLE_) + I sent
a PR to add 41 missing consts
(https://github.com/php/php-src/pull/13340/files)=
=C2=A0- 150+ constants for options such as protocols, HTTP versions, URL follow rules, etc.

I think a more light-weight approach would be to:

=C2=A0- Move all of them to the `\Curl` namespace.
=C2=A0- Rename Curl options to `\Curl\Option` namespace, and rename them, so that `CURLOPT_SSL_VERIFYHOST` becomes `Curl\Option\SSL_VERIFYHOST`
=C2=A0- Rename Curl error codes to similar `\Curl\Error` constants.
=C2=A0- Have the `CurlHandle` object accept options, e.g.
`$ch->setOption(Curl\Option\SSL_VERIFYHOST, 2)`. libcurl Easy handlers do not have a way to retrieve the option once it's set, so there will be no `getOption` either.
=C2=A0- Make Curl throw exceptions, and never `false` on `\Curl\execute()`,=
with the Exception's error code and message mapped to the Curl error code and message. We will not need to bring over `curl_error` or
`curl_errno` functions.

Realistically, I don't think we can deprecate and remove the `\curl_*`<= br> functions any time soon, so this will actually add more maintenance
work for php-src at the end too.

Thank you.
Ayesh.

I'm not even sure it's a= good idea to add those namespaced options: using CURLOPT_SSL_VERIFYHOST is= perfect to find the corresponding curl documentation with your favorite se= arch engine. php's doc is awesome, but it cannot compete with the detai= ls provided by curl's doc on the topic.

Nicola= s
--000000000000d31457063894e3ed--