[RFC][DISCUSSION] Object-oriented curl API v2

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.

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.

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.

Hi all,

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.

To avoid drifting too much from existing expectations about how such a cURL interface ought to look (as vs what happened with the URL RFC) it would be wise to examine existing userland work earlier rather than later.

A brief search at https://packagist.org/?query=curl reveals https://packagist.org/packages/php-curl-class/php-curl-class and https://packagist.org/packages/curl/curl right away, each with millions of downloads already.

These and other userland offerings should help inform the first steps, in any case.

-- pmj

More specifically, since it does introduce an entirely new namespace it
should be considered a “new extension” and must therefore follow the
Exception policy outlined in:
https://github.com/php/policies/blob/main/coding-standards-and-naming.rst#throwables

Embarrassingly, I had read your RFC adding that section - it's kind of
what got me thinking about adding a curl namespace in the first place!

• but I guess I didn't put it into long-term memory. Thanks for the
  catch, I'll update that when I can.

• uses enumerations for curl options and other curl constants

Overall I think the RFC is a good opportunity to clean up a few legacy
oddities in the curl API, but I need to throw in my 2c about enum usage
here, as someone that has actually implemented some complexish
curl-based client [1].

Currently the API is:

 curl_setopt($h, CURLOPT_SMTH, 3);

Now moving this into multiple enums to me brings one major issue, that I
first have to think about which type the option has to then know on
which enum I find it.

I understand this brings type safety on the value side if you have
multiple setOptionInt etc, but that does not seem worth the trade-off to
me. Type safety can already be done in static analyzers as they can see
which option you pass in, they know which value should be allowed.

Then on top of that, assuming we'd put all options in one enum.. I am
still wondering what the added value is compared to simply having the
global constants (they could be namespaced if anything...). It's longer
to type, and does not provide any better autocompletion.
\Curl\Option::ConnectTimeout vs CURLOPT_CONNECT_TIMEOUT sounds ok to me
if people feel strongly pro-enum, but I do really hope it is then a
single enum + setOption() call.

Best,
Jordi

[1]
https://github.com/composer/composer/blob/main/src/Composer/Util/Http/CurlDownloader.php

Jordi Boggiano
@seldaek - https://seld.be

Reading this I can't help but feel like there's some cognitive bias
because you have written a Curl class yourself. The author of a PHP
Class that wraps Curl needs to know about every option and how to
translate them back-and-forth, which is really the insight I take from
your message. As a PHP developer making HTTP requests, I would never
have guessed 270 options for Curl configurations and having them split
into multiple Enums gives me smaller "boxes" that are easier to
mentally parse individually. With that said, splitting enumerations by
type rather than context does weaken the argument of split enums. I
wouldn't be instinctively looking for "what enum do I need that is an
int?" or "what enum do I need that is a string?" unless I already know
the implementation details by heart. The Info and Pause enumerations
seem more useful in that regard as they reduce the scope in which I
need to understand, process and decide.

I will agree here. Splitting enums by type doesn't add much value. Splitting them by topic might, if the topics are sufficiently distinct that a separate method makes sense. I don't know Curl's API well enough to make specific recommendations there.

--Larry Garfield

With that said, for me this also threads into the bikeshedding area
that could spiral into a failed RFC. Be it a single Enum for
everything, constants, context-based enums or type-based enums, I
would much rather have this RFC than not have it. PHP is one of the
most important Web applications in the world and it severely lacks
the ability to simplify Http. We could take inspiration from Python
Requests [1] or Node Fetch [2] as a really simple and
straightforward API that covers the vast majority of cases.

Python Requests and Node Fetch are simple and straightforward for users
because they're not simple and straightforward to develop. A lot of
care and detailed decisions have gone into those APIs to make them feel
simple and straightforward when used.

Python Requests^1 is a massive third-party library that users install
separately from Python. It also depends on urllib3^2, another massive
third-party library that serves as its underlying HTTP client.

Node Fetch uses the WHATWG Fetch Living Standard^3, which, again, is
neither simple nor straightforward. It just feels that way when using it
because they did a damn good job defining it.

As I said earlier,^4 this level of detail should live in userland.
Arguably, as in the case of Fetch, something like this could live in
core. There was an RFC over 10 years ago that proposed moving pecl_http
into core.^5 However, if we decide to go that route, I think it needs
to be a much bigger undertaking, perhaps with a working group formed to
hash out the details and design the API. I think it's better to let
userland handle something like this, so core can focus on optimizations
that reduce the "if it's in C, it'll be faster" arguments.

I take the point that we don't need to go all the way and invent a
RequestClient library in PHP and this RFC is threading on the small
step of converting Curl procedural API into OOP, which is where
Larry and Rowans recommendations about some minor helper methods go
a really really long way compared to where we are today.

I'm fully on board with making the curl extension API easier to use.

Let's clearly state the problem and use-case we're attempting to solve
for and focus on a solution targeting that and nothing more (without
limiting ourselves for future expansion, of course). Maybe after stating
the problem clearly, we'll find it easier to build consensus on a solution.

The RFC hints at type safety and converting the curl procedural API into
OOP as motivating factors. I don't think these clearly state the problem
we're trying to solve, so if they continue to be the motivating factors,
this discussion is bound to continue into bikeshedding territory.

Here are some of the more concrete things I've seen mentioned that hint
at the problem:

From Rowan:

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.

From Marco:

perform basic HTTP requests in a friendly way

These are great starts. Solving for the documentation problem might not
even require changes to the extension. We probably need to further
define what is meant by "friendly," though. Otherwise, we'll find
ourselves back at the bike shed.

So, what's the problem (from a user's perspective) this RFC solves?

Cheers,
Ben

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

Hi Nicolas,
You are right, if we were to rename those constants, we would lose the
"grep-ability" in both libcurl source/docs and many years of existing
open source projects and discussions.

So while keeping the existing option consts, info consts, we do not
have a lot of room to improve it. Perhaps the CurlHandle objects can
accept options similar to how we have date_* functions alongside
DateTime methods. I personally continue to use the functions, but I
won't mind having an OOP API. We can leave it to the library authors
(such as you, Nicolas 💟, Symfony HTTP client is just awesome) to
design more intuitive APIs.

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.

That's a good point, but I do feel like there is value in having these
under a namespace; a part of the reason I am interested in this
proposal is that I'd like to see more of PHP core living under
namespaces, since I think it will present a more consistent vision of
the "standard library". I wonder if there is a way we could preserve
the link, at least? In my proposal, the enum values are equivalent to
their curl constant equivalents, which I thought would help with
discoverability in the documentation.

For the record - and I'll say this elsewhere - based on the discussion
so far I am planning on withdrawing the proposal for separate enums.
I'm still considering using a single enum to group all of these
options, however, instead of constants.

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

So I think we've identified a key disagreement about not just the goal, but the intent. To what extent should PHP core ship with a usable HTTP client?

Right now it ships with Curl, which... in its current form is not usable. It's a low-level tool with an inscrutable API we inherited from C. It's not viable as a user-facing tool. It's a tool that's only useful to people writing client libraries like Guzzle or CurlClass or Symfony HTTP or such.

On the one hand, Marco is correct that for a web-centric language to not ship with a non-sucky way to send web requests is... kinda embarrassing. Even if the use cases where you can't install a 3rd party library are few, they are non-zero. And that also doesn't help new users figure out what to use. (Eg, the person who wrote most of the code for our main application at work, learning PHP as he went, is sending lots of requests using... an ungodly mess of curl that can't even understand. Because he didn't know that things like Guzzle even existed.)

On the other hand, Ben is correct that an HTTP client is a not-small task, with a very deep rabbit hole.

So there's two closely related but distinct asks here:

1. Make working with curl suck less (giving it an OOP interface is part of that but not all)
2. Ship a useful first-party HTTP client that can handle the 80% case, even if it's not full featured.

Beefing up Curl's interface until it fulfills part 2 is one approach, but not the only.

At one extreme would be the "do nothing, status quo is fine" position. Ayesh seems to be close to that position, maybe with a little polish for funsies. The other extreme would essentially be "Guzzle in core," which I don't think anyone is advocating. Where between those extremes we should land is debatable.

Personally I'm of the mind that a simple, basic-features HTTP client in core would be a good thing; that's central enough that it should not be left to userland. It doesn't need to offer every possible feature; no need for async multiplexing, for example. But sending GET and POST requests with straightforward bodies should be table-stakes for a web language, and right now, that's a second class citizen. If it's written in such a way that it can be extended easily in user-space, so much the better.

Whether that basic-features client is Curl itself or a bundled wrapper that uses Curl, I have no strong preference. The challenge of making it separate from Curl is, shocker, that it's bikeshed bait. Does that imply using the new URL/URI classes? Does it imply we need request/response objects? The rabbit hole indeed gets deep fast.

So the first question, I think, is what is the consensus between these three coarse-grained positions:

1. Status quo is fine. PHP core not having a user-friendly way to send HTTP requests is acceptable. Maybe make Curl a little nicer, but only to make life easier for Guzzle et al.
2. We should develop the Curl API until it's usable for basic HTTP behavior, but no further.
3. We should bundle an HTTP client that wraps Curl (with or without minor improvements to Curl), exact scope TBD.

Personally, I'm open to either 2 or 3. 3 is more bikesheddable, but possibly the better end result.

Where does everyone else stand?

--Larry Garfield

I’m also open to 2 or 3, but 3 sounds more like something that I think should live in userland, so I lean much more towards 2.

Cheers,
Ben

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

So I think we've identified a key disagreement about not just the goal,
but the intent. To what extent should PHP core ship with a usable HTTP
client?

Right now it ships with Curl, which... in its current form is not usable.
It's a low-level tool with an inscrutable API we inherited from C. It's
not viable as a user-facing tool. It's a tool that's only useful to people
writing client libraries like Guzzle or CurlClass or Symfony HTTP or such.

On the one hand, Marco is correct that for a web-centric language to not
ship with a non-sucky way to send web requests is... kinda embarrassing.
Even if the use cases where you can't install a 3rd party library are few,
they are non-zero. And that also doesn't help new users figure out what to
use. (Eg, the person who wrote most of the code for our main application
at work, learning PHP as he went, is sending lots of requests using... an
ungodly mess of curl that can't even understand. Because he didn't know
that things like Guzzle even existed.)

On the other hand, Ben is correct that an HTTP client is a not-small task,
with a very deep rabbit hole.

So there's two closely related but distinct asks here:

1. Make working with curl suck less (giving it an OOP interface is part of
   that but not all)
2. Ship a useful first-party HTTP client that can handle the 80% case,
   even if it's not full featured.

Beefing up Curl's interface until it fulfills part 2 is one approach, but
not the only.

At one extreme would be the "do nothing, status quo is fine" position.
Ayesh seems to be close to that position, maybe with a little polish for
funsies. The other extreme would essentially be "Guzzle in core," which I
don't think anyone is advocating. Where between those extremes we should
land is debatable.

Personally I'm of the mind that a simple, basic-features HTTP client in
core would be a good thing; that's central enough that it should not be
left to userland. It doesn't need to offer every possible feature; no need
for async multiplexing, for example. But sending GET and POST requests
with straightforward bodies should be table-stakes for a web language, and
right now, that's a second class citizen. If it's written in such a way
that it can be extended easily in user-space, so much the better.

Whether that basic-features client is Curl itself or a bundled wrapper
that uses Curl, I have no strong preference. The challenge of making it
separate from Curl is, shocker, that it's bikeshed bait. Does that imply
using the new URL/URI classes? Does it imply we need request/response
objects? The rabbit hole indeed gets deep fast.

So the first question, I think, is what is the consensus between these
three coarse-grained positions:

1. Status quo is fine. PHP core not having a user-friendly way to send
   HTTP requests is acceptable. Maybe make Curl a little nicer, but only to
   make life easier for Guzzle et al.
2. We should develop the Curl API until it's usable for basic HTTP
   behavior, but no further.
3. We should bundle an HTTP client that wraps Curl (with or without minor
   improvements to Curl), exact scope TBD.

Personally, I'm open to either 2 or 3. 3 is more bikesheddable, but
possibly the better end result.

Where does everyone else stand?

--Larry Garfield

I think #2 is the way to go. I personally just use Symfony's HTTP Client
99.9% of the time - there is one exception in recent years where I had to
go low-level cURL and craft an extremely specific HTTP request. Yes, it is
a SOAP service for a government system, because of course it is.

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.

Valid. This cannot be avoided if any kind of RFC is to be accepted, so I
think the next best solution is to put effort into documentation and ensure
that things are referenced (like the new Enum options having very obvious
links to the original constants and to the curl documentation), making
discoverability easy.
The good thing is that OOP API is purely new, so there is not going to be
tons of old content about it to make things messy.

Arvīds Godjuks
+371 26 851 664
arvids.godjuks@gmail.com
Telegram: @psihius https://t.me/psihius

Thanks for your thoughtful response, Larry! I agree with your summary.

1. Status quo is fine. PHP core not having a user-friendly way to send HTTP requests is acceptable. Maybe make Curl a little nicer, but only to make life easier for Guzzle et al.
2. We should develop the Curl API until it's usable for basic HTTP behavior, but no further.
3. We should bundle an HTTP client that wraps Curl (with or without minor improvements to Curl), exact scope TBD.

Personally, I'm open to either 2 or 3. 3 is more bikesheddable, but possibly the better end result.

Where does everyone else stand?

Based on the feedback so far (I do plan on waiting for more responses
to your email), and on my own preferences, I wonder if there is a
hybrid option I could propose. Perhaps the RFC could offer both a
\Curl\Handle (tentative name) to address position 1, and a
\Curl\BasicHttpHandle (also tentative name) that addresses position 2?
If people were amenable, I'd even make the BasicHttpHandle a separate
vote.

I agree that 3 is both more bikesheddable and also possibly ideal, but
I feel my above suggestion maybe strikes the right balance between the
"status quo is fine, I don't want to see random HTTP-related methods
on my low(est)-level curl object" and the "I'd like to do basic HTTP
stuff with curl, without a library" crowds.

Barring that, my preference would be 2, but I'd accept 1 just to have
it pass - like I mentioned elsewhere, I think there is value in
introducing namespaces and object-oriented APIs for "modernization"
and language consistency reasons.